Versions Compared

Old Version 15

changes.mady.by.user Pat Sweeney

Saved on

compared with

New Version Current

changes.mady.by.user Devon Gardner

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

To install in Arduino (required for initial install only and currently must be performed on the internal network at the office):

  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”

    Image of the board manager

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

    Image of Gumband Hardware selected in the boards menu

...

  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).

Windows, missing DLL

Depending on your environment you may encounter an error during compilation on Windows. To fix this you’ll need to install the Microsoft C++ runtime libraries https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170

Info

Having trouble programming?

To manually enter the bootloader, reboot the device while holding the user button (useful if the upload fails or a sketch bricks the device). A reboot can be achieved by manually power cycling or pressing the reset button.

...

Configuring the Hardware

Talking to the Device

...

Info

You can send help to see a full list of commands, or see Serial Configuration Interface | Commands

Creating Credentials

To create credentials for the new device, you’ll need to login to app.gumband.com. Follow the steps outlined here or in Hardware UI | Create new Hardware

  1. Navigate to Sites > [Project Site] > Hardware > Create Hardware.

...

2. Create a descriptive name (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”).

The software will automatically generate a unique hardware ID and authentication token to use on the hardware. Copy this token to your clipboard; you’ll need it in a second to finish configuring the hardware.

Note

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

Insert excerpt
Hardware UI
Hardware UI
nameHWUI Create new hardware
nopaneltrue
5. Configure the hardware using the following commands:

Description

Command

Set Hardware ID

write hardware_id <ID>

Set Authentication Token

write auth_token <TOKEN>

Set Cloud Server

write cloud_server

stag

app.gbtt.gumband.com:

1883

8883

Enable Cloud Server

write cloud_enable true

Reboot the device

restart

...

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.

...

Info

See Gumband LED Status for a list of all status LED colors.

Cloud Encryption

Panel
panelIconIdatlassian-flag_on
panelIcon:flag_on:
panelIconText:flag_on:
bgColor

...

#FFEBE6

By default the hardware will try to connect to the cloud with an encrypted connection.
app.gbtt.gumband.com:8883 – TLS encrypted port
app.gbtt.gumband.com:1883 – Unencrypted port

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

Description

Command

Set Cloud Server (Unencrypted)

write cloud_server app.gbtt.gumband.com:1883

Disable TLS encryption

write cloud_tls_enable false

Reboot the device

restart

...

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

      Code Block
      languagearduino
      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:

      Code Block
      languagearduino
      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.

...