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

Dash.timerExpired()

New in Arduino SDK version 0.11.0

Check if the Timer has expired.

Parameters: None

Returns: (bool) – true if timer expired, false if timer is running.

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

Changed in Arduino SDK version 0.11.0

This function has been changed from a blocking call to a non-blocking call. The packet switched connection is automatically made when available. Use this function only to reconnect after a call to .disconnect(). Because it is non-blocking, a return value of true only indicates that the request was received, it does not necessarily indicate the connection was successful. Use .getConnectionStatus() or .isConnected() to determine the current connection state.

Parameters: None

Returns: booltrue if connection initiated or already established, false if the request failed.

HologramCloud.disconnect()

Changed in Arduino SDK version 0.11.0

Explicitly disconnect the packet and circuit switched connections, and power down the modem.

Use this function to turn off the modem for power-saving, but to keep the System processor active to manage the RGB LED and battery charge status (Dash rev 1.2 only). To restart the modem and reconnect to the network, use .connect().

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_REGISTERED (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
  • CLOUD_ERR_MODEM_OFF (15) - Modem is powered off and cannot respond

Parameters: None

Returns: int – The connection status codes.

HologramCloud.isConnected()

New in Arduino SDK version 0.11.0

Check if there is a packet switched connection to the network.

Parameters: None

Returns: booltrue packet switched connection exists, false otherwise.

HologramCloud.isRegistered()

New in Arduino SDK version 0.11.0

Check if there is a circuit switched connection to the network.

Parameters: None

Returns: booltrue circuit switched connection exists, false otherwise.

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.getUTC(dt)

This function signature takes in a rtc_datetime_t struct.

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

To synchronize the Dash RTC to UTC:

rtc_datetime_t dt;
if(HologramCloud.getUTC(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. Call this function to turn on the System processor and the modem after a call to .powerDown().

Parameters: None

Returns: void

HologramCloud.powerDown()

Turn the System processor and modem off. This will greatly lower power consumption, but no network functionality will be available while the modem is off. Nor will System processor functions such as RGB LED and battery charge status (Dash rev 1.2 only).

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

New in Arduino SDK version 0.11.0

The International Mobile Equipment Identity (IMEI) for the modem.

Parameters: None

Returns: String – The IMEI, or Not available if IMEI 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

Set a callback for cloud notification events.

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_REGISTERED (3) – Registered on the network
  • CLOUD_EVENT_CONNECTED (4) – Packet switched connection established

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

New in Arduino SDK version 0.11.0

Returns the state of the battery charger (Dash rev 1.2 only). This is represented by the following return codes:

Charge Status Code:

  • CHARGE_STATUS_FAULT (0) – Charger is in a fault state
  • CHARGE_STATUS_INVALID1 (1) – Charger is in an invalid state
  • CHARGE_STATUS_CHARGING (2) – Charger is charging the battery
  • CHARGE_STATUS_LOW_BATTERY (3) – Charger has detected a low battery condition
  • CHARGE_STATUS_CHARGED (4) – Battery is fully charged
  • CHARGE_STATUS_INVALID5 (5) – Charger is in an invalid state
  • CHARGE_STATUS_NO_BATTERY (12) - No battery is connected
  • CHARGE_STATUS_NO_INPUT (15) - Powered by battery only

Parameters: None

Returns: int – The charge status codes.

HologramCloud.attachHandlerCharge(callback)

New in Arduino SDK version 0.11.0

Set a callback for charge status change events (Dash rev 1.2 only).

void my_charge_handler(charge_status status) {
  switch(status) {
    case CHARGE_STATUS_CHARGED:
      Serial.println("Battery Charged");
      break;
  }
}

void setup() {
    HologramCloud.attachHandlerCharge(my_charge_handler);
}

Parameters:

  • charge_handler (void (*charge_handler)(charge_status status)) – callback function

event_handler Parameters:

  • status (charge_status) – The ID of the charge status change.

Returns: None

HologramCloud.setRGB(name)

New in Arduino SDK version 0.11.0

Set the RGB LED to one of the following colors (Dash rev 1.2 only):

Color Names

MAROON                  = 0x800000
DARK_RED                = 0x8B0000
BROWN                   = 0xA52A2A
FIREBRICK               = 0xB22222
CRIMSON                 = 0xDC143C
RED                     = 0xFF0000
TOMATO                  = 0xFF6347
CORAL                   = 0xFF7F50
INDIAN_RED              = 0xCD5C5C
LIGHT_CORAL             = 0xF08080
DARK_SALMON             = 0xE9967A
SALMON                  = 0xFA8072
LIGHT_SALMON            = 0xFFA07A
ORANGE_RED              = 0xFF4500
DARK_ORANGE             = 0xFF8C00
ORANGE                  = 0xFFA500
GOLD                    = 0xFFD700
DARK_GOLDEN_ROD         = 0xB8860B
GOLDEN_ROD              = 0xDAA520
PALE_GOLDEN_ROD         = 0xEEE8AA
DARK_KHAKI              = 0xBDB76B
KHAKI                   = 0xF0E68C
OLIVE                   = 0x808000
YELLOW                  = 0xFFFF00
YELLOW_GREEN            = 0x9ACD32
DARK_OLIVE_GREEN        = 0x556B2F
OLIVE_DRAB              = 0x6B8E23
LAWN_GREEN              = 0x7CFC00
CHART_REUSE             = 0x7FFF00
GREEN_YELLOW            = 0xADFF2F
DARK_GREEN              = 0x006400
GREEN                   = 0x008000
FOREST_GREEN            = 0x228B22
LIME                    = 0x00FF00
LIME_GREEN              = 0x32CD32
LIGHT_GREEN             = 0x90EE90
PALE_GREEN              = 0x98FB98
DARK_SEA_GREEN          = 0x8FBC8F
MEDIUM_SPRING_GREEN     = 0x00FA9A
SPRING_GREEN            = 0x00FF7F
SEA_GREEN               = 0x2E8B57
MEDIUM_AQUA_MARINE      = 0x66CDAA
MEDIUM_SEA_GREEN        = 0x3CB371
LIGHT_SEA_GREEN         = 0x20B2AA
DARK_SLATE_GRAY         = 0x2F4F4F
TEAL                    = 0x008080
DARK_CYAN               = 0x008B8B
AQUA                    = 0x00FFFF
CYAN                    = 0x00FFFF
LIGHT_CYAN              = 0xE0FFFF
DARK_TURQUOISE          = 0x00CED1
TURQUOISE               = 0x40E0D0
MEDIUM_TURQUOISE        = 0x48D1CC
PALE_TURQUOISE          = 0xAFEEEE
AQUA_MARINE             = 0x7FFFD4
POWDER_BLUE             = 0xB0E0E6
CADET_BLUE              = 0x5F9EA0
STEEL_BLUE              = 0x4682B4
CORN_FLOWER_BLUE        = 0x6495ED
DEEP_SKY_BLUE           = 0x00BFFF
DODGER_BLUE             = 0x1E90FF
LIGHT_BLUE              = 0xADD8E6
SKY_BLUE                = 0x87CEEB
LIGHT_SKY_BLUE          = 0x87CEFA
MIDNIGHT_BLUE           = 0x191970
NAVY                    = 0x000080
DARK_BLUE               = 0x00008B
MEDIUM_BLUE             = 0x0000CD
BLUE                    = 0x0000FF
ROYAL_BLUE              = 0x4169E1
BLUE_VIOLET             = 0x8A2BE2
INDIGO                  = 0x4B0082
DARK_SLATE_BLUE         = 0x483D8B
SLATE_BLUE              = 0x6A5ACD
MEDIUM_SLATE_BLUE       = 0x7B68EE
MEDIUM_PURPLE           = 0x9370DB
DARK_MAGENTA            = 0x8B008B
DARK_VIOLET             = 0x9400D3
DARK_ORCHID             = 0x9932CC
MEDIUM_ORCHID           = 0xBA55D3
PURPLE                  = 0x800080
THISTLE                 = 0xD8BFD8
PLUM                    = 0xDDA0DD
VIOLET                  = 0xEE82EE
MAGENTA                 = 0xFF00FF
ORCHID                  = 0xDA70D6
MEDIUM_VIOLET_RED       = 0xC71585
PALE_VIOLET_RED         = 0xDB7093
DEEP_PINK               = 0xFF1493
HOT_PINK                = 0xFF69B4
LIGHT_PINK              = 0xFFB6C1
PINK                    = 0xFFC0CB
ANTIQUE_WHITE           = 0xFAEBD7
BEIGE                   = 0xF5F5DC
BISQUE                  = 0xFFE4C4
BLANCHED_ALMOND         = 0xFFEBCD
WHEAT                   = 0xF5DEB3
CORN_SILK               = 0xFFF8DC
LEMON_CHIFFON           = 0xFFFACD
LIGHT_GOLDEN_ROD_YELLOW = 0xFAFAD2
LIGHT_YELLOW            = 0xFFFFE0
SADDLE_BROWN            = 0x8B4513
SIENNA                  = 0xA0522D
CHOCOLATE               = 0xD2691E
PERU                    = 0xCD853F
SANDY_BROWN             = 0xF4A460
BURLY_WOOD              = 0xDEB887
TAN                     = 0xD2B48C
ROSY_BROWN              = 0xBC8F8F
MOCCASIN                = 0xFFE4B5
NAVAJO_WHITE            = 0xFFDEAD
PEACH_PUFF              = 0xFFDAB9
MISTY_ROSE              = 0xFFE4E1
LAVENDER_BLUSH          = 0xFFF0F5
LINEN                   = 0xFAF0E6
OLD_LACE                = 0xFDF5E6
PAPAYA_WHIP             = 0xFFEFD5
SEA_SHELL               = 0xFFF5EE
MINT_CREAM              = 0xF5FFFA
SLATE_GRAY              = 0x708090
LIGHT_SLATE_GRAY        = 0x778899
LIGHT_STEEL_BLUE        = 0xB0C4DE
LAVENDER                = 0xE6E6FA
FLORAL_WHITE            = 0xFFFAF0
ALICE_BLUE              = 0xF0F8FF
GHOST_WHITE             = 0xF8F8FF
HONEYDEW                = 0xF0FFF0
IVORY                   = 0xFFFFF0
AZURE                   = 0xF0FFFF
SNOW                    = 0xFFFAFA
BLACK                   = 0x000000
DIM_GRAY                = 0x696969
GRAY                    = 0x808080
DARK_GRAY               = 0xA9A9A9
SILVER                  = 0xC0C0C0
LIGHT_GRAY              = 0xD3D3D3
GAINSBORO               = 0xDCDCDC
WHITE_SMOKE             = 0xF5F5F5
WHITE                   = 0xFFFFFF

Parameters: (String) - case-insensitive color name

Returns: (bool) - true if color is valid and set, false otherwise.

HologramCloud.setRGB(hexcode)

New in Arduino SDK version 0.11.0

Set the RGB LED to an RGB color value (Dash rev 1.2 only). Uses the format: 0xRRGGBB, where each byte is a 0-255 level for red (RR), green (GG), and blue (BB).

Parameters: (int) - RGB value

Returns: (bool) - true if color is set, false otherwise.

HologramCloud.offRGB()

New in Arduino SDK version 0.11.0

Turn off the RGB LED (Dash rev 1.2 only).

Parameters: None

Returns: (bool) - true if turned off, false otherwise.

HologramCloud.setLED(on)

New in Arduino SDK version 0.11.0

Turn on or off the System LED.

Parameters: (bool) - turn on if true, off if false

Returns: (bool) - true if successful, false otherwise.

HologramCloud.resetSystem()

New in Arduino SDK version 0.11.0

Perform a hard-reset of the System processor. Can be used if the System processor becomes unresponsive.

Parameters: None

Returns: None

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