Dash API References

Classes and functions when developing for the Dash in various toolchains

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.

Note: The Hologram Dash is no longer in production.

 

Arduino Compatibility

All built-in Arduino functions are supported in the Dash Arduino environment, as of Arduino SDK version 0.10.3. 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 theconfig parameter to thebegin(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.

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

Note: 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(onms, offms)

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

 

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

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

Note: Removed in Arduino SDK version 0.9.2. Use Charger.batteryMillivolts() instead.

 

Dash.batteryPercentage()

Note:Removed in Arduino SDK version 0.9.2. Use Charger.batteryPercentage() instead.

 

Dash.bootVersion()

Returns a string representation of the boot loader version, in

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

Note: 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: bool — true 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: bool — true 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: bool — true 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: bool — true 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: bool — true 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: bool — true 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: bool — true 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: bool — true 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: bool — true 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: bool — true 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: bool — true 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: bool — true 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: bool — true 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: bool — true 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: bool — true 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: bool — true 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: bool — true 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 and 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: bool — true if successful, false otherwise.

 

HologramCloud.getUTC(dt)

This function signature takes in a rtc_datetime_t struct and 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: bool — true 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 uint8t* content, uint32t length)

HologramCloud.sendMessage(const uint8t* content, uint32t length, const char* tag)

HologramCloud.sendMessage(const uint8t* content, uint32t 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: bool — true 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: bool — true 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 (cloudevent) — 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: bool — true 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 (6) - No battery is connected
• CHARGE_STATUS_NO_INPUT (7) - 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

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: bool — true if successful, false otherwise.

 

DashFlash

New in Arduino SDK version 0.11.1

The DashFlash class provides read/write access to a reserved section of the user microcontroller internal flash. The total size available is 256KB. It is not possible to access, modify or erase the user program using DashFlash. There are several constraints to be aware of when using DashFlash.

Flash memory must be erased before it is written. Erasing flash makes all the bits 1. Writing to flash changes a 1 to a 0. The flash is arranged in 4KB sectors. Before data can be written to a sector, the sector has to be erased. Once erased, any bytes in the sector may be written, but to re-write any bit, the entire sector must first be erased.

The DashFlash can only perform a write if the starting address of the write is a multiple of 8. Any number of bytes may then be written, but the address of the first byte must be 0, 8, 16, 24, 32, ... 262120, 262128, 262136. This is a physical limitation of the flash memory.

bool writeToFlash() {
  //erase the sector so it can be written
  DashFlash.eraseSector(0);

  //start at address 32 (MUST be a multiple of 8)
  DashFlash.beginWrite(32);

  //write 0-19 starting at 32
  for(int i=0; i
    DashFlash.continueWrite(i);
  }


  //complete the write to flash
  DashFlash.endWrite();

  //Read back and verify write
  DashFlash.beginRead(32);
  for(int i=0; i
    uint8_t b = DashFlash.continueRead();
    if(b != i) return false;
  }

  return true;
}

 

DashFlash.eraseSector(address)

Erase the 4KB sector of flash that contains address. 0-4095 erases the first sector, 4096-8191 erases the second sector, and so on.

Parameters:

• address (uint32_t) — the address of the sector to erase

Returns: bool — true if the sector was erased

 

DashFlash.eraseAll()

Erase all the 4KB sectors of flash in the data flash area. This will NOT erase the user application area of flash.

Parameters: None

Returns: bool — true if all the sectors were erased

 

DashFlash.isSectorErased(address)

Check if the 4KB sector of flash that contains address is erased.

Parameters:

• address (uint32_t) — the address of the sector to check

Returns: bool — true if the sector is completely erased (all bytes 0xFF)

 

DashFlash.read(address, buffer, count)

Read the contents of count bytes of the data flash into buffer, starting at address. Address may be in range of 0-262143. The 8-byte address alignment required for writes does not apply to reads, so any address may be used.

Parameters:

• address (uint32_t) — the starting address for the flash read
• buffer (uint8_t *buffer) — destination buffer for the read
• count (size_t) — number of bytes to read

Returns: uint32_t — the number of bytes actually read

 

DashFlash.write(address, buffer, count)

Write the contents of count bytes of buffer to the flash, starting at address. Address may be in range of 0-262136, in multiples of 8 only (8-byte address alignment).

Parameters:

• address (uint32_t) — the starting address for the flash write
• buffer (const void *buffer) — source buffer for the write
• count (size_t) — number of bytes to write

Returns: uint32_t — the number of bytes actually written

 

DashFlash.beginRead(address)

Prepare to read the flash at address.

Parameters:

• address (uint32_t) — the address to begin reading from

Returns: bool — true if the address is valid

 

DashFlash.continueRead()

Read the next byte of flash. Must only be called after beginRead(). Call repeatedly to read the flash byte-by-byte.

Parameters: None

Returns: uint8_t — the next byte read from flash

 

DashFlash.endRead()

Complete the flash read started by beginRead().

Parameters: None

Returns: None

 

DashFlash.beginWrite(address)

Prepare to write to the flash at address. Address may be in range of 0-262136, in multiples of 8 only (8-byte address alignment).

Parameters:

• address (uint32_t) — the address to begin reading from

Returns: bool — true if the address is valid

 

DashFlash.continueWrite(byte)

Write byte to the flash. Must only be called after beginWrite(). Call repeatedly to write to the flash byte-by-byte. Physical writes are buffered until 8 bytes are ready to be written.

Parameters:

• byte (uint8_t) — the byte of data to be written

Returns: bool — true if the byte was written or buffered successfully

 

DashFlash.endWrite()

Complete the flash write started by beginWrite(). Writes any bytes remaining in the write buffer.

Parameters:None

Returns: bool — true if the bytes were written successfully

 

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

Note: 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></message></msglen>

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

Note: 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></body></bodylen></severity></msglen,<severitylen>
          

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