Installation and Setup

To install in Arduino (required for initial install only):

1. Download Arduino (NOT 2.x, This latest version has not yet been confirmed to work with Gumband HDK)

2. Open Arduino

3. Navigate to File > Preferences (or Arduino > Preferences on MacOS)

4. Under Additional Boards Manager URLs add https://bitbucket.org/deeplocal/gumband_arduino_public/raw/main/package_gumband_index.json

5. Navigate to Tools > Boards > Boards Manager

6. Find and install package “Gumband Hardware”
   

   

7. Under Tools > Boards you should now see "Gumband Boards", where you can select “Gumband Hardware”
   

   

Programming the Hardware

 Each hardware device runs 2 programs: 

• The main Gumband Core 

• The user code (your Arduino sketch)

1. To update or install the Gumband Core select the "M0p" core from the boards menu and flash the device with a blank sketch (or any sketch)

   1. Note: This only needs to happen once, either with new blank hardware or to update to the latest Gumband version

2. To upload your sketch select the "M4 (user code)" core from the boards menu and flash the device.

   1. Under File > Examples > Basics are some examples of how to use the device hardware like blinking the on-board LED and using the user button.

   2. Under File > Examples > Gumband API are some examples of using the Gumband API to create properties (hardware endpoints).

Configuring the Hardware

Talking to the Device

New devices need to be configured for the Gumband SDK. This can be done over the USB serial interface.

1. Connect the hardware to your machine using a USB cable and select it in the Tools > Port menu. It should appear as a USB COM Port (standard COM Port drivers should be sufficient for this).

   

2. Open the Serial Monitor in the Arduino IDE (or your serial terminal of choice)
   

   

3. Type then send read ip to verify connectivity

   1. An unconnected or unassigned device should respond 0.0.0.0:0.

Creating Credentials

To create credentials for your hardware device, you’ll need to login to app.gumband.com and have developer-level or manager-level permission.

1. Navigate to a Site under which this hardware will exist.

Sites > [Project Site] > Hardware

2. Click “Create Hardware”.

3. Enter a descriptive name for the hardware device and press “Create”.

Note: this is visible to everyone in the organization so include your name or initials or project name as applicable, for example “Thomas Test” or instead of simply “Test”.

4. Note the Hardware ID and Token

The software will automatically generate a unique hardware ID and authentication token to use on the hardware. Make note of this token or copy it to your clipboard; you’ll need to give it to the hardware to configure it.

Note: if you lose this authentication token, you can create a new one anytime from the ‘Auth’ tab on the dashboard.

5. Configure the hardware using the following commands:

Once your hardware device is plugged into the network via Ethernet cable, it should be online and should appear as connected on the online console in addition to your device’s LED pulsating cyan.

Cloud Encryption

To disable the encryption, further configure the device with the below commands.

Tips for Writing Gumband User Application Code

• Gumband only checks for callbacks once at the end of every iteration of the loop() function. In general, it's a bad idea to use delays within this loop() function because it inhibits the system from checking callbacks constantly.

• When reading data from a callback function, you need to cast the incoming data to get it in a usable form. This allows you to more easily use the data more than once if necessary. The type you cast it to should match the type of data of the peripheral.

  • Ex: Use

    int32_t* dat = (int32_t*)data;

    for the gmbnd_int32 type

  • The Gumband API also includes type casting macros for each supported Gumband datatype. For example, to accomplish the same thing as above using only Gumband API features:

    gmbnd_int32 dat = GUMBAND_INT32(data);

• Peripheral/Property names can only be 15 characters, anything longer will be truncated.

• The on-board LED and button work with digitalWrite() functions using the LED_BUILTIN and BUTTON_BUILTIN pin assignments. However, you can also use the custom gumbandLed() On/Off/Toggle/SetBrightness and gumbandButtonPressed() functions within the Gumband API.

• The on-board button does not need to be initialized with pinMode(); it will work automatically. It will not work properly if reconfigured to INPUT_PULLUP or INPUT_PULLDOWN.

• Initializing pins with pinMode() is not necessary for most I/O. They will be initialized automatically when calling digital/analog read/write. To configure pullup/pulldown resistors, pinMode() is necessary, however.

Command Line Utilities

The Arduino package include an upload utility that communicates with the bootloader and can be executed directly from the command line. The gumband_loader tool is located in tools>gumband_utils directory of the installed package (typically AppData\Local\Arduino15\packages\gumband_arduino for pre 2.0 Arduino IDE under Windows).

The syntax for this tool is as follows: gumband_loader <file> <port>

where:
<file> is any valid *.gbm0 or *.gbm4 file (M0 or M4 application images)
<port> is the COM port that the hardware is connected to.