This page documents methods available when developing code for the Dash microcontroller. Target the Dash in the Arduino IDE by adding the board as described in the guide.

Source code is available on Github. For examples, see our Arduino Examples repository.

Arduino Compatibility

All built-in Arduino functions are supported in the Dash Arduino environment, as of Arduino SDK version 0.10.3.

Additionally, the following items are also provided.

Known Issues

  • Use of tone() and digitalWrite in the same program could have unexpected results. It is recommended to use only one or the other.
  • tone() is only supported on PWM-capable pins.
  • It is recommended to use only one tone() pin at a time.

Constants

  • INPUT_PULLDOWN – Use as an argument to pinMode to set the pin as an input with the internal pull-down resistor enabled.

Structures

  • rtc_datetime_t – The struct has the following properties:
typedef struct RtcDatetime
{
   uint16_t year;    /*!< Range from 1970 to 2099.*/
   uint16_t month;   /*!< Range from 1 to 12.*/
   uint16_t day;     /*!< Range from 1 to 31 (depending on month).*/
   uint16_t hour;    /*!< Range from 0 to 23.*/
   uint16_t minute;  /*!< Range from 0 to 59.*/
   uint8_t second;   /*!< Range from 0 to 59.*/
} rtc_datetime_t;

digitalToggle(pin)

Call this function on an IO pin in OUTPUT mode and the value will change, from LOW to HIGH, or HIGH to LOW.

Parameters:

  • pin (int) – the number or symbol of the IO pin to toggle

Returns: void

tonePlaying()

Check if a tone with a duration provided is still playing. Can be used to pause program execution until the tone has completed.

tone(D1, 220, 3000);          //Play a 220Hz tone for 3 seconds
//perform operations...
while(tonePlaying());         //Wait until tone is finished
//continue with program

Parameters: None

Returns: Boolean. true if duration has not yet expired for a tone, false if no tone is playing.

attachToneInterrupt(callback)

Attach a callback function to the tone complete interrupt. Only one callback function is allowed at any single point in time. Attempting to register another callback function to the tone interrupt will override the previous callback function registered to it. The callback function will be executed when the duration for a call to tone() has expired. This facilitates playing tones in background with no active waiting between notes.

typedef struct {
  uint32_t frequency;
  uint32_t duration;
}note;

note song[] = {
  {261, 300},
  {440, 500},
  {220, 250},
  {466, 375},
  {220, 400},
  {349, 320},
  {0, 2500},
};

int numnotes = sizeof(song)/sizeof(note);

void nextNote(void) {
  static int i = 0;
  tone(L07, song[i].frequency, song[i].duration);
  i++;
  if(i >= numnotes)
    i = 0; //repeat song
}

void setup() {
  attachToneInterrupt(nextNote);
  nextNote();
}

void loop() {
  // code will still execute here...
}

Parameters:

  • callback (void *) – Pointer to a callback function with no parameters.

Returns: void

println(dt);

Additional overload of the print and println functions to print a date time value in format YYYY/MM/DD,hh:mm:ss

Parameters:

  • dt (const rtc_datetime_t &) – Reference to a timestamp.

Returns: size_t – number of bytes printed

Serial Config

New in Arduino SDK version 0.10.4

The Serial0 and Serial2 objects support a subset of the config parameter to the begin(baudrate, config) function.

  • Only 8-bit transfers are supported
  • Only 1 stop bit is supported
  • Parity (None, Odd, Even) is supported

If None is selected for parity, the transfer is a full 8 bits of data. If a parity bit is chosen (either Odd or Even), the data consists of the 7 least significant bits, the most significant bit being discarded for transfers and always 0 for receiving. The data ‘on-the-wire’ has the parity bit as the least significant bit.

Example: Sending the character ‘A’ (0x41)

Serial0.write('A');

None: 0x41 (0100 0001)b
Even: 0x82 (1000 0010)b
 Odd: 0x83 (1000 0011)b

The Serial0.read() function will return 0x41 (‘A’) in all 3 cases.

If the parity does not match, the data is discarded.

Single Wire mode is also supported for half-duplex communication. In this mode both the Transmit and Receive use the same pin, the Transmit pin. In this mode the pin is normally in the Receive state and only switches to Transmit during a write.

The supported pre-defined values for config are:

SERIAL_8N1  //8 data bits, None parity, 1 stop bit, Full Duplex
SERIAL_7E1  //7 data bits, Even parity, 1 stop bit, Full Duplex
SERIAL_7O1  //7 data bits,  Odd parity, 1 stop bit, Full Duplex
SERIAL_8N1H //8 data bits, None parity, 1 stop bit, Half Duplex
SERIAL_7E1H //7 data bits, Even parity, 1 stop bit, Half Duplex
SERIAL_7O1H //7 data bits,  Odd parity, 1 stop bit, Half Duplex

The default value is SERIAL_8N1 if config is not specified, and is the appropriate choice in most cases.

Serial0.begin(9600); //equivalent to Serial0.begin(9600, SERIAL_8N1);
Serial2.begin(115200, SERIAL_7E1H); //Single Wire with Even parity

Constants

Pins

The Dash’s API provides aliases for addressing pins by physical location, GPIO channel, and analog channel. Refer to the Dash datasheet for pinouts for specific Dash variants.

  • L01, L02, R01, R02, etc: Address pins by their location on the left and right side of the board
  • D01, D02, etc: Address digital I/O pins by their GPIO channel
  • A01, A02, etc: Address analog input pins by their analog input channel

Examples:

pinMode(R08, INPUT_PULLUP);   // Set mode for 8th pin on the right side
pinMode(D04, OUTPUT);         // Set mode for GPIO channel 4
int val = analogRead(A01);    // Read from analog input 1

Serial Interfaces

The Dash has several serial channels:

  • SerialUSB – Serial communication over USB. Aliased to Serial.
  • SerialCloud – Communication with the system chip. Writes to this interface are sent as messages to the Hologram Cloud.
  • Serial0 – UART channel 0 (RX0/TX0 pins)
  • Serial2 – UART channel 2 (RX2/TX2 pins)

These instances are compatible with Arduino’s Serial interface.

SerialCloud has been deprecated in Arduino SDK version v0.10.0 and will be removed in the future. Please use the HologramCloud functions documented below.

Dash Instantiation

Dash.begin()

Deprecated in Arduino SDK version 0.9.2. Starting with that version, this method gets called automatically.

Set up interrupts and pin settings that the Dash needs to function. Call this method in your program’s setup() block.

Parameters: None

Returns: void

Dash.end()

Deactivate interrupts and pin settings. There should never be a need to call this explicitly.

Parameters: None

Returns: void

LEDs

Dash.setLED(on)

Turn on or off the user LED.

Parameters:

  • on (boolean) – true turns on the LED, false turns it off.

Returns: void

Dash.toggleLED()

Turn off the LED if it’s on, turn it on if it’s off.

Parameters: None

Returns: void

Dash.pulseLED(on_ms, off_ms)

Repeatedly blink the LED on and off. Calling any other LED-related functions (setLED, toggleLED, etc.) will stop the blinking.

Parameters:

  • on_ms (unsigned int) – Number of milliseconds to leave the LED on.
  • off_ms (unsigned int) – Number of milliseconds for the LED to be off before turning it on again.

Returns: void

Dash.onLED()

Turn on the user LED.

Parameters: None

Returns: void

Dash.offLED()

Turn off the user LED.

Parameters: None

Returns: void

Dash.dimLED(percentage)

Set the LED to a brightness level 0-100

Parameters

  • percentage (byte) – How bright to set the LED, on a range of 0 to 100

Returns: void

Power Management

Dash.snooze(ms)

Pauses the program for the given amount of time. This is a lower-power alternative to Arduino’s standard delay() function.

Parameters:

  • ms (unsigned int) – How many milliseconds to snooze before resuming execution.

Returns: void

Dash.sleep()

Pause execution until an interrupt occurs or serial data is received. Interrupts must be configured with the Arduino attachInterrupt() function.

When an interrupt is triggered, its ISR (callback function) is run, then execution resumes on the line after the sleep() call.

Parameters: None

Returns: void

Dash.deepSleep()

Put the device into the lowest-power state until the device receives a wakeup interrupt. See attachWakeup() for details.

Parameters: None

Returns: void

Dash.deepSleepSec(sec)

Put the device into the lowest-power state for the specified amount of time. Does not wake up for any I/O interrupts.

Parameters:

  • sec (unsigned int) – How many seconds to deep sleep before resuming execution.

Returns: void

Dash.deepSleepMin(min)

Put the device into the lowest-power state for the specified amount of time. Does not wake up for any I/O interrupts.

Parameters:

  • min (unsigned int) – How many minutes to deep sleep before resuming execution.

Returns: void

Dash.deepSleepHour(hours)

Put the device into the lowest-power state for the specified amount of time. Does not wake up for any I/O interrupts.

Parameters:

  • hours (unsigned int) – How many hours to deep sleep before resuming execution.

Returns: void

Dash.deepSleepDay(days)

Put the device into the lowest-power state for the specified amount of time. Does not wake up for any I/O interrupts.

Parameters:

  • days (unsigned int) – How many days to deep sleep before resuming execution.

Returns: void

Dash.deepSleepAtMostSec(sec)

Put the device into the lowest-power state for the specified amount of time. Will wake up before the time limit if the device receives a wakeup interrupt. See attachWakeup() for details.

Parameters:

  • sec (unsigned int) – Max seconds to deep sleep before resuming execution.

Returns: void

Dash.deepSleepAtMostMin(min)

Put the device into the lowest-power state for the specified amount of time. Will wake up before the time limit if the device receives a wakeup interrupt. See attachWakeup() for details.

Parameters:

  • min (unsigned int) – Max minutes to deep sleep before resuming execution.

Returns: void

Dash.deepSleepAtMostHour(hours)

Put the device into the lowest-power state for the specified amount of time. Will wake up before the time limit if the device receives a wakeup interrupt. See attachWakeup() for details.

Parameters:

  • hours (unsigned int) – Max hours to deep sleep before resuming execution.

Returns: void

Dash.deepSleepAtMostDay(days)

Put the device into the lowest-power state for the specified amount of time. Will wake up before the time limit if the device receives a wakeup interrupt. See attachWakeup() for details.

Parameters:

  • days (unsigned int) – Max days to deep sleep before resuming execution.

Returns: void

Dash.shutdown()

Put the device into the lowest-power state until the device receives a wakeup interrupt.

Put the device into the lowest-power state (same as deep sleep). When the device receives a wakeup interrupt, the processor resets and your program begins execution in its setup() function again.

See attachWakeup() for details on wakeup interrupts.

Parameters: None

Returns: void

Interrupts

The Dash uses Arduino’s standard attachInterrupt() function for configuring interrupts. These standard interrupts can be used to execute a function when the level of an input pin changes, and also to resume execution after calling Dash.sleep().

In addition to the standard interrupts, the Dash uses a special interrupt on certain pins to wake the device from low-power deep sleep. These wakeup interrupts are configured with the Dash.attachWakeup() function.

Dash.attachWakeup(pin, mode)

Configure a wakeup interrupt to wake the device from deep sleep. Must use a pin wired to the Low Level Wakeup Unit–see WKUP pins on the Dash pinout.

Parameters

  • pin (unsigned int) – Pin to monitor
  • mode (unsigned int) – The change that should trigger the interrupt. Must be one of three constants:
    • RISING - wake when the pin goes from low to high
    • FALLING - wake when the pin goes from high to low
    • CHANGE - wake when the pin changes, either high->low or low->high

Returns: void

Dash.detachWakeup(pin)

Disable a wakeup interrupt that was previously configured.

Parameters

  • pin (unsigned int) – Pin to stop monitoring

Returns: void

Dash.clearWakeup()

Disable all configured wakeup interrupts.

Parameters: None

Returns: void

System Information

Dash.batteryMillivolts()

Removed in Arudino SDK version 0.9.2. Use Charger.batteryMillivolts() instead.

Dash.batteryPercentage()

Removed in Arudino SDK version 0.9.2. Use Charger.batteryPercentage() instead.

Dash.bootVersion()

Returns a string representation of the boot loader version, in <major>.<minor>.<revision> format. For example, 2.1.1.

Parameters: None

Returns: Version string, e.g. 2.1.1

Dash.bootVersionNumber()

Returns an integer representation of the boot loader version. The smallest byte is the revision, the next byte is the minor, and the third least significant byte is the major version number. For example, version 2.1.1 would be represented as 0x020101.

Parameters: None

Returns: Version int

Dash.serialNumber()

New in Arduino SDK version 0.9.2

Returns a string representation of the USB serial number, which consists of 32 hexadecimal characters.

Parameters: None

Returns: Serial number string, e.g. 001600005DD301A14E4531735001001B

Timer

The Dash features a hardware timer that will call a function on expiration. The timer can be used in either one-shot or repeating mode. The maximum timer interval is 4,294,966 seconds or 4,294,967,295 milliseconds.

void my_timer_handler(void) {
  Dash.toggleLED();
}

void setup() {
    //use the Timer to toggle the LED every 10 seconds
    Dash.attachTimer(my_timer_handler);
    Dash.startTimerSec(10, true);
}

Dash.attachTimer(callback)

Set the callback function that is called upon timer expiration.

Attach a callback function that is called upon timer expiration. Only one callback function is allowed at any single point in time. Attempting to register another callback function to the timer will override the previous callback function registered to it.

Parameters:

  • callback (void *) – Pointer to a callback function with no parameters.

Returns: void

Dash.detachTimer()

Disconnect the callback from the timer. No function is called on timer expiration.

Parameters: None

Returns: void

Dash.startTimerMS(interval_ms, repeat)

Start the hardware timer and set the expiration for interval_ms milliseconds, with the timer optionally restarting upon expiration.

Parameters:

  • interval_ms (unsigned int) – the number of milliseconds until timer expiration.

  • repeat (boolean) – true to restart the timer on expiration, false to run the timer only once. Default to false if omitted.

Returns: void

Dash.startTimerSec(interval_sec, repeat)

Start the hardware timer and set the expiration for interval_sec seconds, with the timer optionally restarting upon expiration.

Parameters:

  • interval_sec (unsigned int) – the number of seconds until timer expiration.

  • repeat (boolean) – true to restart the timer on expiration, false to run the timer only once. Default to false if omitted.

Returns: void

Dash.stopTimer()

Stop a currently running timer. No effect if timer is not currently active.

Parameters: None

Returns: void

Battery Charger

The Dash features an onboard battery charging circuit. When the jumpers are set to power the Dash from the battery, the Dash will also charge the battery from the USB_5V line. Control the specific charge/discharge behavior using the Charger class on Dash 1.1 hardware only.

Charger.begin()

Deprecated in Arduino SDK version 0.9.2. Starting with that version, this method gets called automatically.

Activate charger control logic. Must be called before manually starting or stopping charging with enable().

Parameters: None

Returns: Boolean. true if the charger is working properly, false if the charger detects a problem

Charger.batteryMillivolts()

New in Arduino SDK version 0.9.2

Reads the battery level in millivolts. Will only return a valid value if the board is configured for battery operation via the jumper settings.

Parameters: None

Returns: (unsigned int) Battery level in millivolts (1000 = 1 volt)

Charger.lastMillivolts()

Returns the last read battery level in millivolts. Will only return a valid value if the board is configured for battery operation via the jumper settings.

Parameters: None

Returns: (unsigned int) Battery level in millivolts (1000 = 1 volt)

Charger.batteryPercentage()

New in Arduino SDK version 0.9.2

Reads the battery level as a percentage (0-100). Will only return a valid value if the board is configured for battery operation via the jumper settings.

Note

This battery percentage returned will be undefined if no battery is connected.

Parameters: None

Returns: (byte) Battery level as a percentage.

Charger.lastPercentage()

New in Arduino SDK version 0.9.2

Returns the last read battery level as a percentage (0-100). Will only return a valid value if the board is configured for battery operation via the jumper settings.

Note

This battery percentage returned will be undefined if no battery is connected.

Parameters: None

Returns: (byte) Battery level as a percentage.

Charger.beginAutoPercentage(minutes, percentage)

Activate charger control logic, automatically switching between charge and discharge based on the battery percentage.

Parameters:

  • minutes (unsigned int) – Number of minutes between checking the battery level. Smaller intervals increase power draw if the Dash needs to come out of sleep to check the level. Too large of an interval can cause the charger to go into faulted shutdown from low voltage. A reasonable starting value is 20 minutes.
  • percentage (unsigned int) – Start charging if the battery drops below this percentage, as returned from Charger.batteryPercentage(). Default value is 90.

Note

This function has effect on Dash 1.1 hardware only.

Charger.beginAutoMillivolts(minutes, millivolts)

Activate charger control logic, automatically switching between charge and discharge based on the battery voltage.

Parameters:

  • minutes (unsigned int) – Number of minutes between checking the battery level. Smaller intervals increase power draw if the Dash needs to come out of sleep to check the level. Too large of an interval can cause the charger to go into faulted shutdown from low voltage. A reasonable starting value is 20 minutes.
  • millivolts (unsigned int) – Start charging if the battery drops below this voltage, as returned from Charger.batteryMillivolts(). Default value is 3900 (3.9V).

Note

This function has effect on Dash 1.1 hardware only.

Charger.end()

Deactivate charger software control logic.

Parameters: None

Returns: void

Charger.isControllable()

Returns whether or not the charger can be enabled/disabled.

Note

This function will return true on Dash 1.1 hardware only.

Parameters: None

Returns: Boolean. true if the charger circuit can be enabled/disabled, false if it cannot.

Charger.isEnabled()

Returns whether the charger circuit is hardware-enabled.

Parameters: None

Returns: Boolean. true if the charger circuit is hardware-enabled, false if it is disabled via hardware control.

Charger.enable(enabled)

Hardware enable/disable of the charger circuit. Can be used to override the overcharge protection shutdown of the charger.

Note: If the charger enters overcharge shutdown (the battery is connected, a charging power source is connected and the battery is not yet fully charged, but charging has stopped), disable and enable the charger to reset and resume charging.

Note

This function has effect on Dash 1.1 hardware only.

Note

Overcharging can damage or destroy the battery.

Parameters:

  • enabled (bool) – true to enable charge circuit, false to disable it.

Returns: void

Charger.checkPercentage(percentage)

Ensure the charger is in the correct charge/discharge state based on a given threshold percentage. beginAutoPercentage() uses this same logic, just on a periodic basis.

Parameters:

  • percentage (unsigned int) – Start charging if the battery is below this percentage, as returned from Charger.batteryPercentage(). If the charger is already charging, will only switch to discharging if the battery is at 100%. Default value is 90.

Note

This function has effect on Dash 1.1 hardware only.

Charger.checkMillivolts(millivolts)

Ensure the charger is in the correct charge/discharge state based on a given threshold voltage. beginAutoMillivolts() uses this same logic, just on a periodic basis.

Parameters:

  • millivolts (unsigned int) – Start charging if the battery is below this voltage, as returned from Charger.batteryMillivolts(). If the charger is already charging, will only switch to discharging if the battery is at 100%. Default value is 3900 (3.9V).

Note

This function has effect on Dash 1.1 hardware only.

Clock

The Dash features a Real Time Clock (RTC) with an alarm function. Set and control these timers and alarms using the Clock class. When the Dash is powered on, the clock will default to epoch time (January 1, 1970), and begin counting up automatically. Set the appropriate date and time with the interfaces below. It is important to note that Clock interfaces are persistent as long as the Dash is powered. For example, if an alarm is set and the User Reset button is pressed, the time will not be reset and the alarm will still be active. The time continues to increment, even with the Dash in deep sleep. An alarm expiration will wake the Dash from Sleep and Deep Sleep.

Note

This Clock class is only functional on Dash 1.1 and above hardware.

Clock.alarmExpired()

Returns true if alarm is not set or has expired, false otherwise.

Parameters: None

Returns: booltrue if alarm is expired, false otherwise.

Clock.counter()

Returns the clock timestamp/counter in seconds since epoch time.

Parameters: None

Returns: uint32_t – The clock timestamp/counter in seconds since epoch time.

Clock.setAlarm(dt)

Set an alarm at the time represented in the given rtc_datetime_t struct. By registering a callback function via the .attachAlarmInterrupt(callback) call described below, the callback function will be executed on alarm expiration. Note that the alarm time must be greater than the current time.

Note

Only one alarm can be set at any given point in time. If '.setAlarm' is called a second time before the previous alarm expires, the second (latest) alarm will override the previous alarm.

Parameters:

  • dt (const rtc_datetime_t &) – Reference to an Alarm timestamp.

Returns: booltrue if the alarm is set successfully, false otherwise.

Clock.setAlarm(seconds)

Set an alarm for the seconds since epoch (Jan 1, 1970). See Clock.setAlarm(dt) for details.

Parameters:

  • seconds (uint32_t) – Timestamp for the alarm in seconds.

Returns: booltrue if the alarm is set successfully, false otherwise.

Clock.setAlarmSecondsFromNow(seconds)

Set an alarm for the given number of seconds after the current time. See Clock.setAlarm(dt) for details.

Parameters:

  • seconds (uint32_t) – Number of seconds from now.

Returns: booltrue if the alarm is set successfully, false otherwise.

Clock.setAlarmMinutesFromNow(minutes)

Set an alarm for the given number of minutes after the current time. See Clock.setAlarm(dt) for details.

Parameters:

  • minutes (uint32_t) – Number of minutes from now.

Returns: booltrue if the alarm is set successfully, false otherwise.

Clock.setAlarmHoursFromNow(hours)

Set an alarm for the given number of hours after the current time. See Clock.setAlarm(dt) for details.

Parameters:

  • hours (uint32_t) – Number of hours from now.

Returns: booltrue if the alarm is set successfully, false otherwise.

Clock.setAlarmDaysFromNow(days)

Set an alarm for the given number of days after the current time. See Clock.setAlarm(dt) for details.

Parameters:

  • days (uint32_t) – Number of days from now.

Returns: booltrue if the alarm is set successfully, false otherwise.

Clock.adjust(ticks)

Adjust the number of RTC clock ticks per second. The ticks parameter can either be a negative or positive offset. This fine tunes the 32,768 input clock to the RTC. By adding/subtracting ticks per second, the accuracy of 1 second can be improved. Adjustments can be made for environment temperature or variations between crystals.

Parameters:

  • ticks (int8_t) – The RTC clock tick offset.

Returns: void

Clock.adjusted()

Returns the configured number of ticks per second.

Parameters: None

Returns: int – The configured number of ticks per second.

Clock.isRunning()

Returns true if the clock is running.

Parameters: None

Returns: booltrue if it is running, false otherwise.

Clock.wasReset()

Returns true if the clock was reset to epoch time (Jan 1, 1970) on the last system reset.

Parameters: None

Returns: booltrue if the clock was reset on the last system reset, false otherwise.

Clock.setDateTime(dt)

Sets the clock based on the given year, month, day, hour, minute and second parameters. This function takes a reference to a rtc_datetime_t struct.

Parameters:

  • dt (const rtc_datetime_t &) – RtcDatetime struct.

Returns: booltrue if the date and time can be set, false otherwise.

Clock.setDateTime(year, month, day, hour, minute, second)

Sets the clock based on the given year, month, day, hour, minute and second parameters.

Parameters:

  • year (uint6_t)
  • month (uint6_t)
  • day (uint6_t)
  • hour (uint6_t)
  • minute (uint6_t)
  • second (uint6_t)

Returns: booltrue if the date and time can be set, false otherwise.

Clock.setDate(year, month, day)

Sets the clock date based on the given year, month, and day parameters. This does not change the existing hour, minute and second values.

Parameters:

  • year (uint6_t)
  • month (uint6_t)
  • day (uint6_t)

Returns: booltrue if the date can be set, false otherwise.

Clock.setTime(hour, minute, second)

Sets the clock time based on the given hour, minute, and second parameters. This does not change the existing year, month and day values.

Parameters:

  • hour (uint6_t)
  • minute (uint6_t)
  • second (uint6_t)

Returns: booltrue if the time can be set, false otherwise.

Clock.currentDateTime()

Returns a formatted date and time string (yyyy/mm/dd,hh:mm:ss). If the clock has not been set, this will be the epoch time plus the time lapse since the Dash was powered on.

Parameters: None

Returns: String – a formatted date and time string (1970/12/31,15:50:22).

Clock.currentDate()

Returns a formatted date string (yyyy/mm/dd), where yyyy is the year, mm is the month and dd is the date. If the clock has not been set, this will be the epoch time plus the time lapse since the Dash was powered on.

Parameters: None

Returns: String – a formatted date string (1970/12/31).

Clock.currentTime()

Returns a formatted time string (hh:mm:ss), where hh is the hour, mm is the minute and ss is the second. If the clock has not been set, this will be the epoch time plus the time lapse since the Dash was powered on.

Parameters: None

Returns: String – a formatted time string (00:55:03).

Clock.cancelAlarm()

Cancels the alarm.

Parameters: None

Returns: void

Clock.attachAlarmInterrupt(callback)

Attach a callback function to the alarm interrupt. Only one callback function is allowed at any single point in time. Attempting to register another callback function to the alarm interrupt will override the previous callback function registered to it.

Parameters:

  • callback (void *) – Pointer to a callback function with no parameters.

Returns: void

HologramCloud

The HologramCloud class provides a programatic interface to interact with the Hologram Cloud. Connect and send/receive messages to/from the cloud using the functions below.

HologramCloud.connect(reconnect)

Establish a packet switched connection to the cell tower. This is optional because calling .sendMessage() will connect as needed. This is a blocking call with a max timeout of 3 minutes to find a tower to connect to. To minimize this blocking time, check to see if a tower has already been found by calling .getSignalStrength(). If connect fails (returns false), call .getConnectionStatus() to determine the reason.

Parameters:

  • reconnect (bool) – An optional reconnect flag that enables connection retries. Default to false if omitted.

Returns: booltrue if successful, false otherwise.

HologramCloud.disconnect()

Explicitly disconnect from the packet switched connection.

Parameters: None

Returns: booltrue if successful, false otherwise.

HologramCloud.getConnectionStatus()

Returns the cell network connection status. This is represented by the following return codes:

Connection Status Code:

  • CLOUD_DISCONNECTED (0) – No packet switched connection
  • CLOUD_CONNECTED (1) – Packet switched connection established
  • CLOUD_ERR_UNAVAILABLE (2) – Could not communicate with the modem
  • CLOUD_ERR_SIM (3) – A valid SIM card was not found
  • CLOUD_ERR_UNREGISTERED (4) – Could not register on the network
  • CLOUD_ERR_SIGNAL (5) – No tower was found
  • CLOUD_ERR_CONNECT (12) - SIM card is not active

Parameters: None

Returns: int – The connection status codes.

HologramCloud.getSignalStrength()

Returns the Received Signal Strength Indication (RSSI) of the cell network connection.

Signal Strength Code:

  • 0: -113 dBm or less
  • 1: -111 dBm
  • 2 to 30: -109 to -53 dBm with 2 dBm steps
  • 31 to 98 – -51 dBm or greater
  • 99 – No signal

Parameters: None

Returns: int – the signal strength.

HologramCloud.getNetworkTime(dt)

This function signature takes in a rtc_datetime_t struct.

Gets the current network time. If a tower has not yet been found, network time is not available.

To synchronize the Dash RTC to network time:

rtc_datetime_t dt;
if(HologramCloud.getNetworkTime(dt)) {
    Clock.setDateTime(dt);
}

Parameters:

  • dt (rtc_datetime_t &) – reference to a date time struct.

Returns: booltrue if successful, false otherwise.

HologramCloud.powerUp()

Power up the modem. This is optional as any cell network related commands will invoke a power up call.

Parameters: None

Returns: void

HologramCloud.powerDown()

Turn the modem off. This will greatly lower power consumption, but no network functionality will be available while the modem is off.

Parameters: None

Returns: void

HologramCloud.pollEvents()

Manually check for events, such as an SMS received. This function is called automatically before powering down the modem and after each run of the loop() function. For most applications this function will not need to be called explicitly.

Parameters: None

Returns: void

HologramCloud.clear()

Explicitly clear the contents of the message buffer. See .sendMessage() for the details of message buffering.

Parameters: None

Returns: void

HologramCloud.checkSMS()

Returns the number of queued SMS messages received.

Parameters: None

Returns: int – The number of queued SMS messages received.

HologramCloud.attachHandlerSMS(sms_handler)

Register an SMS handler that will be executed whenever an SMS is received.

void my_sms_handler(const String &sender, const rtc_datetime_t &timestamp, const String &message) {
    //take action on the SMS
}

void setup() {
    HologramCloud.attachHandlerSMS(my_sms_handler);
}

Parameters:

  • sms_handler (void * sms_handler(sender, timestamp, message))

sms_handler Parameters:

  • sender (const String &) – SMS sender.
  • timestamp (const rtc_datetime_t &) – Timestamp in rtc-datetime_t format. In local time as of Arduino SDK version v0.10.2.
  • message (const String &) – SMS body.

Returns: void

HologramCloud.sendMessage()

HologramCloud.sendMessage(const char *content)

HologramCloud.sendMessage(const String &content)

HologramCloud.sendMessage(const char *content, const char *tag)

HologramCloud.sendMessage(const String &content, const String &tag)

HologramCloud.sendMessage(const String &content, const char* tag)

HologramCloud.sendMessage(const char* content, const String &tag)

HologramCloud.sendMessage(const uint8_t* content, uint32_t length)

HologramCloud.sendMessage(const uint8_t* content, uint32_t length, const char* tag)

HologramCloud.sendMessage(const uint8_t* content, uint32_t length, const String &tag)

The maximum message content is 4096 bytes. The maximum number of topics (tags) is 10. The maximum size of a topic (tag) is 63.

HologramCloud contains a single message buffer that consists of the contents of the message along with any attached topics (tags). The message buffer is initially empty, but can be appended to using any Arduino Print functions.

Calling .sendMessage(...) with any parameters (content and/or topics) appends those parameters to the existing message buffer, then the message is sent. Example

//Send "Hello, World!" with the topic: "greeting"
HologramCloud.sendMessage("Hello, World!", "greeting");

//Send "Battery: 78%" for example
HologramCloud.print("Battery: ");
HologramCloud.print(Charger.batteryPercentage());
HologramCloud.sendMessage("%");

Calling .sendMessage() with no parameters sends the contents of the message buffer.

//Send "Signal: 21" for example
HologramCloud.print("Signal: ");
HologramCloud.print(HologramCloud.getSignalStrength());
HologramCloud.sendMessage();

Repeating a call to .sendMessage() without first modifying the contents of the buffer will resend the last message.

//Send "Battery: 78%" with topic "battery" for example
HologramCloud.print("Battery: ");
HologramCloud.print(Charger.batteryPercentage());
HologramCloud.attachTag("battery");
if(!HologramCloud.sendMessage("%")) {
    //failed to send the message
    //wait 1 minute and try again
    Dash.snooze(60*1000);

    //Retry sending "Battery: 78%"
    HologramCloud.sendMessage();
}

//Start a new message
HologramCloud.attachTag("my_data");
//Buffer emptied and the new topic is appended to the buffer

//Send "This is my data" with topic "my_data"
HologramCloud.sendMessage("This is my data");

After any .sendMessage call, the buffer contents are retained until the buffer is modified by calling any of the following:

  • HologramCloud.attachTag(...)
  • HologramCloud.print(...)
  • HologramCloud.println(...)
  • HologramCloud.write(...)
  • HologramCloud.sendMessage(...)

At which point the buffer is cleared and the new content is appended.

Parameters:

  • content – The content payload.
  • tag – Tags that the content is associated with.
  • length – The payload length.

Returns: booltrue if successful, false otherwise.

HologramCloud.attachTag(const char *tag)

HologramCloud.attachTag(const String &tag)

Attaches a tag to the message buffer. Returns true if successful, false otherwise.

Parameters:

  • tag – Tag name.

Returns: booltrue if successful, false otherwise.

HologramCloud.write(x)

Append a single byte to the message buffer.

Parameters:

  • x (uint8_t) – Input byte.

Returns: size_t – the size of a successfully written byte (1), 0 otherwise.

HologramCloud.systemVersion()

The version number for the System Firmware.

Parameters: None

Returns: String – A formatted version string (“0.9.8”).

HologramCloud.getICCID()

New in Arduino SDK version 0.10.1

The Integrated Circuit Card Identifier (ICCID) for the SIM card.

Parameters: None

Returns: String – The ICCID, or Not available if ICCID could not be read.

HologramCloud.getNetworkOperator()

New in Arduino SDK version 0.10.1

The current network operator in use.

Parameters: None

Returns: String – The operator name, e.g. AT&T, or Not available if the operator could not be read.

HologramCloud.listen(port)

New in Arduino SDK version 0.10.1

Open a server socket on the specified port to receive messages. Only one server socket is available at a time. Calling listen will close an existing server socket before opening the next one. Calling disconnect or powerDown will close an existing server socket. Server socket is also closed if packeted switched connection is closed by the network. See attachHandlerNotify.

Incoming messages are auto-responded to with OK, which will appear in the device data log with topic _API_RESP_.

Parameters:

  • port (int) – local port to bind the server socket to.

Returns: int – 0 if socket open failed, > 0 on success.

HologramCloud.attachHandlerInbound(callback)

New in Arduino SDK version 0.10.1

Register a callback function that will be executed whenever an inbound message is received. Also specifies a local buffer that is used to hold the message.

#define SIZE_INBOUND 4096
char buffer_inbound[SIZE_INBOUND];

void my_inbound_handler(int length) {
    //NULL terminate if the data is text/printable
    buffer_inbound[length] = 0;

    //take action on the message, which is stored in
    //buffer_inbound with length bytes
}

void setup() {
    HologramCloud.attachHandlerInbound(my_inbound_handler, buffer_inbound, SIZE_INBOUND-1);
}

Parameters:

  • inbound_handler (void (*inbound_handler)(int length)) – callback function
  • buffer (void *) – destination buffer
  • ‘length’ (int) – size of buffer, use 1 less than size for NULL-terminated text

inbound_handler Parameters:

  • length (int) – length of the message contents.

Returns: void

HologramCloud.attachHandlerNotify(callback)

New in Arduino SDK version 0.10.1

Returns the cell network connection status. This is represented by the following return codes:

void my_notify_handler(cloud_event e) {
  switch(e) {
    case CLOUD_EVENT_DISCONNECTED:
      Serial.println("Disconnected from Cloud");
      break;
  }
}

void setup() {
    HologramCloud.attachHandlerNotify(my_notify_handler);
}

cloud_event Code:

  • CLOUD_EVENT_NONE (0) – No event
  • CLOUD_EVENT_DISCONNECTED (1) – Packet switched connection disconnected by network
  • CLOUD_EVENT_UNREGISTERED (2) – Unregistered from the network
  • CLOUD_EVENT_REGISTERD (3) – Registered on the network

Parameters:

  • event_handler (void (*event_handler)(cloud_event e)) – callback function

event_handler Parameters:

  • e (cloud_event) – The ID of the event that occurred.

Returns: None

HologramCloud.getLocation(accuracy, max_timeout)

New in Arduino SDK version 0.10.2

Request approximate current location using cell connection information. The function registered by attachHandlerLocation() is called upon receipt of the location information. Use of this function requires a data connection and uses approximately 1KB of data.

Parameters:

  • accuracy (int) - optional requested accuracy, in meters (1-999999). If not specified, 10 meters.
  • max_timeout (int) - optional maximum wait time, in seconds (1-999). If not specified, 360 seconds.

Returns: booltrue if successful, false otherwise.

HologramCloud.attachHandlerLocation(location_handler)

Register a location handler that will be executed whenever a getLocation() response is received.

void cloud_location(const rtc_datetime_t &timestamp, const String &lat, const String &lon, int altitude, int uncertainty) {
    //take action on the location data
}

void setup() {
    HologramCloud.attachHandlerLocation(my_location_handler);
}

Parameters:

  • location_handler (void * location_handler(timestamp, lat, lon, altitude, uncertainty))

location_handler Parameters:

  • timestamp (const rtc_datetime_t &) – Timestamp in rtc-datetime_t format using local time.
  • lat (const String &) – Latitude in floating point String format.
  • lon (const String &) – Longitude in floating point String format.
  • altitude (int) – Altitude in meters.
  • uncertainty (int) – accuracy of the location data, in meters.

Returns: void

HologramCloud.enterPassthrough()

New in Arduino SDK version 0.10.2

Ends active management of the modem and all HologramCloud features, putting the System processor in passthrough mode. Use SerialSystem serial port for accessing the modem directly via AT commands. Call HologramCloud.begin() to resume normal operation.

Note

Use of this function is not officially supported and is not recommended. It is provided as a convenience for advanced users only.

Parameters: None

Returns: booltrue if successful, false otherwise.

System Events

These events are sent from the system firmware over the SerialCloud interface. They can be useful for debugging or accessing certain information not available through direct APIs.

SMSRCVD

SMSRCVD has been deprecated in Arduino SDK version v0.10.0 and will be removed in the future. Please use HologramCloud‘s .checkSMS() and .attachHandlerSMS() instead.

+EVENT:SMSRCVD,<msglen>,<message>

The device has received an SMS, either from the Hologram dashboard, API, or from another mobile device sending to the device’s phone number.

  • msglen – Length of the received message
  • message – The text of the SMS. Terminated by a newline character.

Example:

+EVENT:SMSRCVD,13,Hello, World!

See the RGB LED sketch for an example of parsing SMS messages.

LOG

LOG messages have been removed as of in Arduino SDK version v0.10.0. Please use HologramCloud‘s functions for operational feedback instead.

+EVENT:LOG,<msglen>,<severitylen>,<severity>,<bodylen>,<body>

System log messages. Messages show cellular connection status and other internal information.

  • msglen – Total number of characters in the rest of the event string.
  • severitylen – Length of the severity string
  • severity – One of: DEBUG, INFO, WARN, CRIT
  • bodylen – Number of characters of the log body
  • body – Text body of the log message.

Example:

+EVENT:LOG,38,5,DEBUG,27,Opening connection to cloud