@Andrew
Thanks for your questions and we’ll be using them to improve the clarity in the documentation. I’ll answer your specific questions here and we’ll be updating the documentation over the coming days.
It’s probably most helpful to start with an example to see the features used in code. From the IDE select
Examples/DashExamples/hologram_dash_cloud
or on Github
That walks you through using HologramCloud.
On to your questions…
- If HologramCloud.sendMessage(…) is blocking, what is the maximum time it will block?
To send a message the modem has to be powered, associated with a tower, and connected to the network. Worst case would be the modem is powered off (HologramCloud.powerDown()) and sendMessage is called. You can call HologramCloud.sendMessage without explicitly calling powerUp or connect.
HologramCloud.powerUp() can take several seconds for the modem to fully boot after being powered down. Once booted, the modem attempts to associate with a tower asynchronously.
HologramCloud.connect() has a hard timeout at 3 minutes, but will most likely return within 2 minutes. The major factor here is cell coverage. If in range of a tower, this call will be < 1 second.
sendMessage will return in < 1 second if already connected and in cell coverage.
To minimize blocking, you can call HologramCloud.getSignalStrength() to check for coverage. If that call returns 99 (no coverage), then you may want to skip the HologramCloud.sendMessage() call.
- Are there any non-blocking calls to send the message buffer content and if so, what are they and what are the calls to determine send status?
All the HologramCloud.sendMessage() calls are blocking. Using the signal strength strategy above will minimize blocking time.
- In the context of HologramCloud.write(x), does “reset” mean empty any previous content of the message buffer? Given that all calls to send a message appear to be blocking, I am not sure what else it could mean. If it does mean to empty the buffer, I am not sure what this function is to be used for.
The docs description for HologramCloud.write(x) is misleading and will be changed. That call will add a byte to the message buffer.
- There is no documentation for HologramCloud.print(). Does it have the same signatures as Serial.print()?
- Is HologramCloud and extension of Serial?
HologramCloud implements the same print and println functions that Arduino Serial uses. Calling those functions adds the output to the message buffer.
The message buffer consists of the message contents and the tags. The buffer is ‘fixed’ once a sendMessage call is made so that the same message can be resent with HologramCloud.sendMessage() (no parameters). This is useful if a message send failed and you want to try the same message again without re-printing to the buffer.
The buffer contents are retained after a call to sendMessage until the buffer is written to again. This is best demonstrated by example:
//write a message to the buffer,
HologramCloud.print("Value: ");
HologramCloud.print(32);
//buffer contents are now "Value: 32"
bool success = !HologramCloud.sendMessage(".00");
//Now the buffer contents are "Value: 32.00" and the message was sent
if(!success) {
//failed, so let's try again in 30 seconds...
Dash.snooze(30000);
//We haven't changed the buffer since the last call to sendMessage, so send the same message again:
//"Value: 32.00"
HologramCloud.sendMessage();
}
HologramCloud.sendMessage("Hello, World!");
//this call changes the buffer since the last sendMessage, so we start a new message
//Buffer contents: "Hello, World"
//Let's send "Hello, World!", since it is still in the buffer
HologramCloud.sendMessage();
HologramCloud.print("It was the best of times, it was the blurst of times");
//This is the first write to the buffer after sending, so start a new message
HologramCloud.sendMessage();
//Send the contents of the buffer, "It was the best of times, it was the blurst of times"
- Is the Clock class persistent across calls to Dash.deepSleep?
The Clock class controls the Real-Time Clock on the Dash. This clock counts seconds while the Dash is powered. Only completely removing power from the Dash resets this clock, which starts at Jan 1, 1970 00:00:00. Resetting the Dash user processor, programming the Dash, and putting the Dash in sleep or deep sleep does not affect the Clock. It continues to tick as long as power is applied.
- Will the Clock alarm functions wake the Dash out of deep sleep?
The alarm will wake the Dash from deep sleep and that is demonstrated in the hologram_dash_cloud example sketch referenced above.
- For the Clock.wasReset() function, what are the causes of clock reset?
Clock.wasReset() returns true only if the Clock was reset on the last processor boot, meaning power was just applied. You can use that function to check if the time needs to be updated. And if you are within cell coverage, just sync the clock to network time!
rtc_datetime_t dt;
if(HologramCloud.getNetworkTime(dt)) {
Clock.setDateTime(dt);
I hope this can help you move forward with the new cloud interface!
