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 --version, 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 3.4.0
  

Running the tests on Windows

To run the tests on Windows, you will need to install the 'gcc' compiler. We recommend downloading it via 'MinGW-64'.

• Download MinGW-w64 with GCC v6.3.0
• Decompress that file somewhere on your system - for example in c:\mingw-64
• Add the compiler to your PATH environment variables
  • Type 'system' in the Windows start menu and Open the 'System' control panel
  • Click 'Advanced System Settings'
  • Click 'Environment Variables'
  • Edit 'Path'
  • Add C:\mingw-64\i686-6.3.0-release-posix-dwarf-rt_v5-rev2\mingw32\bin

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

If you are upgrading

If you are doing an upgrade, rather than a new install, it's always a good idea to run platformio update before building a new firmware. This will make sure you have the most recent version of platformio.

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

On Windows and MacOS, you will need to press the PROGRAM button, located in the bottom-left corner of KBox. On Linux, your this is usually not needed.

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 upload the WiFi firmware:

$ platformio run -e esp -t upload

Uploading a WiFi firmware relies on the host firmware detecting that you are trying to program the WiFi module. This is accomplished by detecting when the serial port is set to 230400 bauds. This has been tested on Linux/Windows/macOS (see #5).

If it does not work, you can still upload the programmer only onto the host and try flashing again:

   $ platformio run -e program-esp -t upload
   $ platformio run -e esp -t upload

Debug output will be available on the NMEA2 output of KBox at 920800/8/N/1. You will need a serial adapter to receive it.

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":

You can also open a Terminal window in Atom and type the command manually:

platformio run -e host -t upload
platformio run -e esp -t upload