Installing the SDK

In order to start using the SDK, we need to set up the environment and install tools. This guide assumes a computer running Windows. It is also possible to use Linux for the build, but some tools, such as Texas Instruments SmartRF Flasher2, do not work under Linux.

Overview

Most of the firmware is already compiled into binary form, and supplied as libraries in the libs/ directory. You don't need to do anything with these, they are automatically included in the firmware during the build process.

Your custom application and any drivers you use are written in the C language, and will include header files specific for your hardware target, and call certain Thingsquare modules. You write and develop the application and custom drivers in any text editor you like, such as Notepad++, Sublime Text, Atom, Vim, emacs, Eclipse and so on. The SDK makes no assumption of this and you are free to use any you like.

Here are some alternatives,

The build process automatically compiles your source files and links everything into a binary file that you program your hardware target with.

Build environment

The build scripts needs a Linux-like environment and tools common on Linux, so on Windows we need to install the Cygwin utility which provides this for us.

When installing Cygwin, you get to choose which utilities to install aside from the core functionality. Here, we need to install at least the wget utility so that the installation script will work.

Further, we need to install the Java JRE and a hardware flash tool to program our firmware onto the hardware target with.

Hardware flashing utility

To get the hardware to run the application firmware we will write, we need a utility to transfer the compiled binary to the hardware itself. For TI CC1310, TI CC1350, TI CC2650, TI CC2538 based hardware we use the Texas Instruments SmartRF Flasher2. Note the 2 since the version that does not have it is for completely different CPUs and will not work. You can download it for free from Texas Instruments.

Java

We also need Java JRE for building the binaries. Download and install the latest version for your system, eg JRE 8u112 for Windows x64 Offline.

Cygwin shell

To run the build process, we will need a shell. The shell is the environment we will work within to start a compilation from. On Linux and macOS, one of the most common shells is called bash. On Windows we need to install Cygwin.

To download and install Cygwin, the process is something like this. You download a installation utility and run it. Use the 32-bit version even if you have a 64-bit computer. If you make a mistake during the process, or want to install further utilities, you can re-run this installation utility and mark the new utilities for installation.

When you run the installer, it will first ask a few initial questions. Answer them as follows (they are all the defaults) and press Next.

  • Install from Internet
  • Root directory C:\cygwin and All users
  • accept the local package directory it suggests
  • Direct Connection

Then it will ask for a site ("mirror") to download from. Pick anyone, eg the suggested default.

The Cygwin installer will present a list of available utilities that it can install with the shell. Here we need to pick a few to make the build system work.

Some utilities are by default selected for installation. On the far left in the list there are double arrows in a circle. If it says anything other than Skip it will install that particular utility. To select a utility for installation, you click the double-arrow so that it says a version number and not Skip.

Search for wget in the search box, mark it for installation. Search for make. There are a few similar, but the one to choose is described as make: the GNU version of the make utility. Mark it for installation. Then press Next. The Cygwin installation will proceed with the installation.

Compiler

Download and installation of the compiler is automatically handled by the script, this is for reference or manual installation.

We are using the free and open source GCC suite of compiler and tools. This download is maintained by ARM. Choose the latest for your platform. This needs to be unzipped, and the path to the compiler bin subdirectory added to PATH. The installation script will handle this.

The firmware SDK currently do not support other compilers (eg Keil, IAR).

Reboot

After all these installations, it may be best to reboot the computer. Then we will run the installation script the downloads and install the rest.

Starting a shell

Starting a shell is just starting an application in windows. Look for Cygwin Terminal (Terminal is another word for Shell). One way is to press the windows-button on the keyboard and start typing cygwin and it will show up as the Cygwin Terminal.

Running the installation script

The installation script will download additional utilities to Cygwin, download the compiler, and download Jacksum. It will set up a directory structure for the SDK, tools, and projects. Finally, it will set up so that the Cygwin shell will find the tools. It may take a couple of minutes to run since it will download large files.

The installation script requires two tools to have been installed with Cygwin: make and wget. If you forgot to install them, run the Cygwin installation file setup-x86.exe again.

Run the installation like this:

  • make sure you are connected to the Internet before you start, since the installation will download files
  • open a Cygwin terminal: press the Windows-button and type cygwin, click the "Cygwin terminal" icon
  • in the terminal, type cygstart ., this will open a file explorer window at the current directory location
  • there, create a new folder, eg temp and copy the SDK zip-file there
  • unzip it at the current location
  • back in the terminal, type cd temp/, then make install

The installation script will now run in the Terminal and open the new location of the SDK when done. You might be prompted whether to proceed or not.

An example directory structure

It's important to set up a directory structure that is easy to maintain and allows version control of your projects without too much hassle. The script sets one up. If you prefer your own directory structure, you have to inspect the script and pick the relevant parts of the installation and perform them manually. This section describes the directory structure that the installation script will set up for you.

Overview

The script sets up a directory structure as such,

c:\development\tools\
c:\development\sdk\
c:\development\projects\

The respective directories are,

  • tools/ directory for compiler and other tools
  • sdk/ directory for the SDK
  • projects/ for your projects. One directory per project, and eg a common directory for custom drivers

SDK versions

The SDK is delivered as a zip-file, eg sdk-v1.2.0.zip. If you have more than one version of the SDK at the same time, you may keep them in subdirectories (ensure to update your project Makefiles accordingly),

c:\development\projects\sdk\sdk-1.1.12\
c:\development\projects\sdk\sdk-1.2.0\

Otherwise, just unzip the SDK into the sdk/ directory.

Projects

It's good to keep the projects separate from the SDK. That way, you can easily update the SDK when new versions are released, and your version control is simpler.

Let each project reside in a directory of its own. Shared drivers may reside in a common driver directory to avoid duplication of files, which would quickly be hard to maintain.

The common driver directory may contain a number of drivers, here for example drivers for bmp185 and adxl345 sensors respectively.

c:\development\projects\common\
    bmp185.c
    bmp185.h
    adxl345.c
    adxl345.h

A project directory will at the very minimum include two files, an application source code file and a Makefile. Here for example a smart street light application,

c:\development\projects\smart-street-lights\
    streetlight-app.c
    Makefile

The Makefile tells the build tool where the rest of the SDK is, and if there are any more files to include in the compilation. Change the path to the SDK to eg SDK=../../sdk.

We strongly recommend using version control. There are a number of version control systems available, eg git, Mercurial, svn. Of these, we at Thingsquare recommend and use git internally, as does many other organizations. How to use git is out of scope of this document, but guides are easy to find with a quick search using your favorite search Internet engine for eg "git tutorial".