Getting Started with Hurricane Development
Follow the steps below to get started developing applications for the hurricane board. If you are looking for instructions on loading existing Hurricane applications through the Leaderboard see here.
Note: The Hurricane board is currently supported under the Gecko OS alpha program. The production Hurricane board will include an onboard debugger and the software will be included directly in the Gecko OS Application SDK making the steps below simpler.
Hardware Requirements
- Hurricane Board
- Simplicity Debug adapter + Samtec cable (SLSDA001A)
- Wireless Starter Kit (WSTK - BRD4001A) or any other compatible starter kit.
- Mini USB cable (plugs into the WSTK)
- Micro USB cable (plugs into the Hurricane board)
Software Requirements
- Gecko OS Studio (GSS)
- A terminal program configured to COM parameters 115200, 8N1.
- For Windows, use Tera Term, RealTerm, Terminal, etc.
- For a Mac, use CoolTerm or equivalent. The terminal can be accessed using /dev/tty.SLAB_USBtoUART.
- CP210x USB to UART VCP Driver
- Hurricane App source code
- Direct Download from GitHub - https://github.com/SiliconLabs/hurricane/archive/master.zip
- GitHub Repository - https://github.com/SiliconLabs/hurricane.git
Setup for Programming Hurricane
To program and debug the WGM160P, the WSTK must be setup as a debug adapter and connected to Hurricane.
Hardware Setup
If your WSTK is installed with a WGM160P (or other) Silabs radio board, remove it from the WSTK main board to avoid confusion as to which device you are developing with.
To connect the hardware, follow these steps in the order shown:
1. Install the Simplicity Debug Adapter on the WSTK.
2. Plug the WSTK into your computer with the USB-mini cable.
3. Plug the Hurricane board into your computer with the USB-micro cable.
4. With the above steps complete, now connect the WSTK Debug Adapter and Hurricane boards together with the grey ribbon cable, taking care to connect the ribbon cable to the
Cortex
connector on the Simplicity Debug Adapter.
Note! It is important to power-up the WSTK and Hurricane boards separately. Failure to do so may cause the WSTK to malfunction. If Simplicity Commander cannot find the WSTK in the following steps, disconnect all boards and be sure to follow the steps above in the order shown.
Launch Simplicity Commander
With Gecko OS Studio (GSS) installed, Simplicity Commander is located at the following location (choose the location to suit your platform):
Platform | Commander Location |
---|---|
Windows | C:\Users\<user>\AppData\Roaming\Gecko OS Studio\tools\tools\commander\win32 |
OS X | ~/Library/Application\ Support/Gecko\ OS\ Studio/tools/tools/commander/osx/MacOS/commander |
Open Simplicity Commander and select Adapter: Connect
to connect to the WSTK as shown in the screen capture.
Connect in Debug Mode
Follow the screen capture to :
1. Set the WSTK
Debug Mode
toOut
(the yellow LED next to the Debug connector on the WSTK illuminates indicating debug mode is set to Out).
2. Connect to the WGM160P on Hurricane by selecting the button Target :
Connect
.
Confirm the Target
Confirm the target shown on Simplicity Commander is WGM160PX22KGA
as shown in the screen capture.
Finish up
Close Simplicity Commander and Open Gecko OS Studio (GSS). The device information in GSS should indicate the WSTK is in debug out mode as shown in the screen capture below.
Note! To return to using your WSTK for development with a radio board, Debug Mode
must be set to MCU
(instead of OUT
).
Flash Gecko OS to your Hurricane Board
The process below will flash the latest version of standard Gecko OS to the Hurricane board. This process will also claim the Hurricane board to your Zentri DMS account.
On GSS, click the Setup Device with Gecko OS
button to flash the latest version of Gecko OS to your device.
GSS takes a few seconds to set up your device.
When the Device Ready
notice appears, your device has a standard Gecko OS image for your platform.
You can now connect to the device via the UART and use the Command API. See Opening a Gecko OS Terminal.
Note! The Hurricane COM port on PC appears as a Silicon Labs CP210x USB to UART Bridge
device (and on Mac, /dev/tty.SLAB_USBtoUART
). Do NOT connect to the J-Link CDC UART Port
which is the interface to the WSTK debug hardware.
When you move to other GSS screens, the Setup Device with Gecko OS
button appears again. There is no need to set up the device again.
After completing this step, the Hurricane board will be running stock Gecko OS and not a 'Hurricane Application.' The following steps will describe how to develop a Hurricane application. Alternatively you can now install a Leaderboard Demo
Clone a Project
For this exercise we will use the introductory Hello World
example provided by GSS. We will clone this example, then modify it to run as a Hurricane App. To start, we need to clone the example as described in the following steps.
For a more advanced example see the DMS Telemetry and Cloud Connector Tutorial.
STEP 1. With Gecko OS Studio (GSS) open, choose Projects
in the navigation column to the left.
STEP 2. Select the Clone Example
button
STEP 3. Ensure that Target
is set to WGM160P_BETA
. If the board is connected before the Clone Example
button is clicked then the WGM160P_BETA
target should be pre-selected for you. If not, you will need to manually change it to WGM160P_BETA
.
Note! The production release of Hurricane boards will contain production
WGM160P
devices in which case the target will beWGM160P
(notWGM160P_BETA
).
STEP 4. Under Intro Examples
choose the hello_world
example and then select Clone
.
When Clone is selected, GSS creates the project which includes downloading the SDK and setting up the Gecko OS device for development.
STEP 5. When GSS finishes creating the project, open the project in the Gecko OS IDE by selecting the Open in IDE
button. If you have not previously installed the IDE, select the button Install IDE
before continuing.
Setup Device (if required)
If the device was connected to the PC at the time the project was cloned, then GSS already setup the device and you can skip to the next section. However, if the device was not connected, or if you wish to use a different device for development, then you must setup the device for development first.
Setup your device by double clicking on the Setup Device
target under the hello_world
project Build Targets
or using the Gecko OS | Setup Device
menu item.
Build, Download and Run the Project
The project is almost ready to be built and downloaded to the Hurricane board. However, the hello_world
example in the Gecko OS App SDK was configured to run on a WSTK, so it does not include the Hurricane setup menu, display library, sensor drivers or other features required by a Hurricane Application. In the next section we will turn this example into a true Hurricane App. Nevertheless, it is instructive to ensure the project builds and runs before we modify it to work with Hurricane.
STEP 1. Under the hello_world
project Build Targets
, double-click on Download Application and Resources
as show below. Alternately, right click on the hello_world
project name and select the Build/Download/Run
menu.
STEP 2. Once the project has been built and downloaded, open your terminal program and press the reset button on the Hurricane board.
Note! The Hurricane COM port on PC appears as a Silicon Labs CP210x USB to UART Bridge
device (and on Mac, /dev/tty.SLAB_USBtoUART
). Do NOT connect to the J-Link CDC UART Port
which is the interface to the WSTK debug hardware.
STEP 3. After pressing the Reset button on Hurricane, you should see output on your terminal similar to the following:
[Ready]
LOCAL>
Hello world!!
Patch the SDK
Use the following procedure to download Hurricane software components and patch the SDK. At the completion of this step the SDK will contain all the necessary source code and components to develop a Hurricane application.
Note! The Hurricane source code and sensor libraries will be included in a future SDK release; this procedure will not be needed after that occurs. Additionally, the patch procedure only works for PC at the moment, support for Mac is in progress).
STEP 1. Download the Hurricane software from Github using one of the links below (these links both point to the same repository). The first link directly downloads a zip file of the latest code. The second link is provided for those familiar with git and who prefer to work directly with the Github repo.
Download Type | Github Link |
---|---|
Zipfile | https://github.com/SiliconLabs/hurricane/archive/master.zip |
Github Repo | https://github.com/SiliconLabs/hurricane.git |
STEP 2. If you chose the zipfile download, uncompress the files to a local folder on your PC
STEP 3. Browse to the folder on your PC containing the downloaded repository and run the executable hurricane_sdk_patch.exe
STEP 4. A popup window will ask you to confirm that you would like to patch the SDK. Select Yes
.
STEP 5. Select the Gecko OS App SDK that will be used for the project and select Ok
.
Note! Since the WGM160P_BETA
target was selected when the project was cloned, the SDK is found under the sdk-wgm160p_beta folder in your Gecko OS workspace. The particular SDK being used by a project is determined at the time the project is created or cloned. The SDK is automatically downloaded, if needed, to the workspace directory. If you have cloned multiple projects, it is possible that you have multiple SDKs downloaded and it is important to determine the correct one. One way to be sure of the correct SDK is to use a text editor to open the make.bat
file in the root directory of the project and search for the following line (on Windows systems):
SET GECKO_OS_SDK_PATH=C:\Users\<YOUR_USERNAME>\gecko_os_workspace\sdk-wgm160p_beta\4.0.17-1377
STEP 6. If the patch is successful, a dialog similar to the following will appear.
STEP 7. You should now see hurricane
folders in the SDK under applications/gecko_os
and components/gecko_os
as shown below.
Edit the Project to make a 'Hurricane App'
The following steps will convert the standard hello_world
example into a 'Hurricane App' complete with setup menu, display, and sensor drivers. These basic steps can be used to turn any Gecko OS application into a Hurricane App.
STEP 1. Right Click on the hello_world
project and select Properties
.
STEP 2. Under C/C++ Build->Settings->Components
add the Hurricane component as shown below.
- components.gecko_os.hurricane
STEP 3. Edit the source code in main.c of the hello_world
project as described below. You can view the full completed code here: main.c
3(a). Include the hurricane.h
header at the top of the file
#include "hurricane.h"
3(b). Define a hurricane_demo_t
global variable above the definition of gos_app_init()
as shown below
hurricane_demo_t demo_info =
{ .demo_name = "Hello World", // Demo name used on LCD
.start_demo_callback = start_demo_handler, // Function called when user selects Run
.stop_demo_callback = stop_demo_handler, // Function called when leaving the demo and returning to hurricane setup
.draw_splash_screen_callback = NULL, // NULL = Do not override splash screen display function
.demo_splash_screen_arg = NULL, // Splash screen jpeg file. NULL = text only
.splash_font_color = HURRICANE_SPLASH_DEFAULT_FONT_COLOR, // Color of the splash screen navigation text
.splash_screen_timeout_ms = 0 // Splash screen timeout (0 = no timeout)
};
3(c). Replace the function gos_app_init()
with the following version. When the Gecko OS app runs, the Hurricane initialization function is called.
/*************************************************************************************************/
void gos_app_init(void)
{
hurricane_init(&demo_info);
}
3(d). Add the following demo_handler()
and stop_demo_handler()
functions underneath the function gos_app_init()
. The Hurricane demo runs when theRun
menu item is selected on the Hurricane main menu.
static void start_demo_handler(void *arg)
{
// Print to the log bus
GOS_LOG(APPLICATION_START_LINE);
// Print to the LCD
hurricane_draw_message_screen("==| Hello World Demo |==", GUI_TA_HCENTER | GUI_TA_VCENTER, "", "");
}
static void stop_demo_handler(void *arg)
{ GOS_LOG("Exiting Hurricane Demo");
}
Rebuild and Download the new Hurricane App
After making the changes described in the previous section, rebuild the app by double clicking on Download Application and Resources
under the project Build Targets
.
When the application launches you will see the Hurricane intro animation appear followed by the application splash screen allowing you to enter the setup menu or launch the application.
Your application now has all of the features needed to access the functionality of a Hurricane board.
Note! The build target Download Application and Resources
must be used the first time to ensure that all the newly added Hurricane resources are downloaded to flash memory on the device.
In future, for changes to source code only, the build target Download Application
can be used to speed up the download process.
Browse the Hurricane Menu
On the splash screen page, press
Button 1
to enter the Hurricane setup menu. Navigate to the page:> System Diagnostics-->View Raw Sensor Data
. This page displays live data from the various sensors on the Hurricane board.Test the sensor readings by:
a. Hovering your hand over the board to see the Proximity and Gesture values changing
b. Cover the Ambient Light Sensor (ALS) to see the ALS reading drop
c. Place your finger on the Relative Humidity/Temperature sensor to see the Temp and Humidity values change
Browse the other menu items under
System Diagnostics
.
Setup Wi-Fi
To Setup Wi-Fi, navigate back to the Main Menu and choose the menu item
Setup Wi-Fi
Follow the instructions on the screen to setup the Wi-Fi connection to a wireless access point
Note! In the project makefile hello_world.mk
you can add the following line to prevent the need to re-setup your Wi-Fi every time you re-build and re-download your application.
PRESERVE_NVM := 1
Launch the Hello World App
Navigate back to the main menu and choose
Start Demo (Hello World)
From the splash screen press
Button 2
(corresponding toRun
) to start the demo."Hello World" displays on both the screen and the device console output.