Developer Setup

Thanks to PlatformIO it is very easy to develop for KBox on Windows, Linux, Mac OS.

Installation

Installing PlatformIO

The general steps are the same for all platforms:

• Make sure you have python 2.7 installed and that it is in your system path. If you open a terminal (or command line in Windows) and type python -v, you should see something like this:

   $ python --version
   Python 2.7.11
  

  To install python on Windows, download an installer here.

• Make sure you have the python package manager pip

  • On Windows, it will be automatically installed with python.

  • On Mac OS:

       $ sudo easy_install pip
    

  • On Linux:

       $ sudo apt-get install python-pip
    

• Update the python package manager pip

   $ pip install -U pip
  

  (On Linux you might need to use sudo)

• Install PlatformIO via pip

   $ pip install -U platformio
  

  (On Linux you might need to use sudo)

• Make sure PlatformIO is working

   $ platformio --version
   PlatformIO, version 2.9.1
  

Installing Atom

This step is optional.

Even if you are having trouble with Atom, you will still be able to compile and upload the firmware. You will just need a different text editor.

If you do not already have a favorite IDE, you can use Atom. It's a free and very capable solution!

• Get Atom for your platform from https://atom.io/.
• When the installation is done, open the Settings page (click on the cog igon in the left-most bar)
• Open the "Install" pane to install packages
• Type "platformio" in the search box and install platformio-ide
• Restart Atom after the installation and open the project
• Watch the "Getting started with Atom" video on the Atom documentation page

Usage

Building KBox firmware

To build KBox firmware, make sure you are in the kbox-firmware directory and run:

$ platformio run -e host

To upload KBox firmware, first make sure you are connected via USB and then run:

$ platformio run -e host -t upload

Most of the time, this command will be able to automatically re-program KBox firmware but in some cases, you might be asked to press the "RESET" or "PROGRAM" button. It is the button in the bottom left of the board.

Building and flashing the KBox WiFi firmware

The WiFi chip is a separate micro-controller and has it's own program. The source code for the WiFi chip is in the src/esp folder of the project.

To build the WiFi firmware, run:

$ platformio run -e esp

To flash the WiFi firmware, you must first flash a special program in the main micro-controller. That program will allow you to upload the WiFi firmware.

To build and upload the special firmware:

$ platformio run -e program-esp -t upload

When you upload the special firmware upload image, the led on the top right corner will be green to show that the board is ready to receive the WiFi firmware. The "running light" led on the bottom left corner will blink when data is sent or received.

To upload the WiFi firmware:

$ platformio run -e esp -t upload

Note: There is a known bug which prevents this from working at the moment. Until we fix this bug, you can use esptool.py to flash the firmware:

$ esptool.py --port /dev/ttyACM0 write_flash 0x0 .pioens/esp/firmware.bin

Using Atom to build and flash

If you are using Atom, you can choose which program you want to work on (the main firmware host, the wifi firmware esp or the special firmware to upload the wifi firmware program-esp) via the selector at the bottom of the screen:

Just follow the instructions above, and select a similar command. For example, to flash the main firmware, you need to choose the Upload option with environment equal to "host":

Using OpenOCD to debug KBox

Note: this has been tested on Linux only at the moment.

KBox includes a 10 pin standardized Cortex debug connector. This connector allows us to connect a debugger and truly debug the code running on the board.

We recommend using a CMSIS-DAP compatible SWD/JTAG connector. The Armstart IBDAP-CMSIS-DAP is only $19 and widely available.

Follow the Armstart instructions to compile OpenOCD with CMSIS-DAP support.

To run OpenOCD, simply type:

$ openocd -f openocd.cfg
Open On-Chip Debugger 0.10.0-dev-00191-gae8cdc1 (2016-01-16-20:05)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
Info : only one transport option; autoselect 'swd'
Info : add flash_bank kinetis k40.flash
adapter speed: 1000 kHz
none separate
cortex_m reset_config sysresetreq
adapter speed: 1000 kHz
srst_only separate srst_nogate srst_open_drain connect_deassert_srst
Info : add flash_bank kinetis pflash.0
Info : CMSIS-DAP: SWD  Supported
Info : CMSIS-DAP: JTAG Supported
Info : CMSIS-DAP: Interface Initialised (SWD)
Info : CMSIS-DAP: FW Version = 1.0
Info : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 1 TDO = 1 nTRST = 0 nRESET = 1
Info : CMSIS-DAP: Interface ready
Info : clock speed 1000 kHz
Info : SWD IDCODE 0x2ba01477
Info : k40.cpu: hardware has 6 breakpoints, 4 watchpoints
Info : MDM: Chip is unsecured. Continuing.

Now open a different terminal to flash or debug the program.

Flashing a firmware

$ platformio run
[ ... building the .elf file ... ]
$ arm-none-eabi-objcopy -O binary .pioenvs/teensy31/firmware.elf
firmware.bin
$ telnet localhost 4444
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger
> reset halt
MDM: Chip is unsecured. Continuing.
k40.cpu: target state: halted
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x000001bc msp: 0x20008000
> flash write_image erase firmware.bin 0x0
auto erase enabled
Probing flash info for bank 0
flash configuration field erased, please reset the device
wrote 79872 bytes from file firmware.bin in 4.921926s (15.847 KiB/s)
>
>
> reset run
MDM: Chip is unsecured. Continuing.

Debugging a firmware

$ arm-none-eabi-gdb .pioenvs/teensy31/firmware.elf
GNU gdb (GNU Tools for ARM Embedded Processors) 7.10.1.20151217-cvs
Copyright (C) 2015 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "--host=x86_64-unknown-linux-gnu --target=arm-none-eabi".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from .pioenvs/teensy31/firmware.elf...done.
(gdb) target remote localhost:3333
Remote debugging using localhost:3333
0x0000a534 in ILI9341_t3::waitTransmitComplete (this=0x1fff9d88, mcr=2149515264)
    at .pioenvs/teensy31/ILI9341_t3/ILI9341_t3.h:254
254                             uint32_t sr = KINETISK_SPI0.SR;
(gdb) break EncoderTestPage.cpp:25
Breakpoint 1 at 0x958: file src/EncoderTestPage.cpp, line 25.
(gdb) c
Continuing.
Note: automatically using hardware breakpoints for read-only addresses.

Breakpoint 1, EncoderTestPage::processEvent (this=0x1fff9e20, e=...) at src/EncoderTestPage.cpp:26
26        if (longClickTrigger && millis() > longClickTrigger) {
(gdb) p longClickTrigger
$1 = 0
(gdb) n
25      bool EncoderTestPage::processEvent(const TickEvent &e) {
(gdb) step
26        if (longClickTrigger && millis() > longClickTrigger) {
(gdb)
31        timer = e.getMillis();
(gdb) p timer
$2 = 5834
(gdb)

To load a firmware with GDB, simply use the load command:

(gdb) load
Loading section .text, size 0x125ac lma 0x0
Loading section .fini, size 0x4 lma 0x125ac
Loading section .ARM.exidx, size 0x8 lma 0x125b0
Loading section .data, size 0xe4c lma 0x125b8
Start address 0x0, load size 78852
Transfer rate: 14 KB/sec, 9856 bytes/write.
(gdb)