Commands and variables
Two basic information flows between devices and the server are commands and variables. They are used internally by the system, and can be used in custom applications. Commands and variables are used to change run-time configurations, change program flow, and for the device to share information, eg sensor data.
Refer to the Thingsquare Callbacks documentation for how to receive notifications in firmware applications when commands and variables are received, and the REST API documentation for how to set and read them over the server.
Commands
Built-in Commands
The system internals makes use of several commands, which must not be used by customer applications for any intent or purpose, or undefined behavior will be the result.
The following commands are built-in and can be used for the intended purpose only.
The frmt
Command
The frmt
command will tell the device to factory reset.
There is no particular action needed in firmware, the internal system handles this by itself.
It will erase all information stored in non-volatile storage related to the connection and identity at the server, and the network credentials to connect to a mesh access point.
After the erase is done, the device will reboot and appear as a new device. It will continue running the firmware image that was in use prior to the command, but need to be invited to a mesh network again, and subsequently perform a first-connect to the server.
The idfy
Command
The idfy
command will tell the device to run the identify
routine.
By default, this will blink the LEDs. If the lighting library is used, this will cause the lighting callbacks to be invoked; this can be used for example to blink not on-board debugging LEDs, but eg a complete street light.
If the lighting library is not used, the firmware must have one or more LEDs defined in order to show something. See the documentation on how to set LEDs.
Customer Application Commands
Customer applications may define commands on their own. If so, they must be using the following format in order not to conflict with the built-in commands and functionality.
Customer commands must be four (4) letters long and start with capital C
. Eg, the following commands are ok,
Cset
Crbt
Cabc
Example
Receiving a Custom Command
With this example, we set up a listener for the custom application command Cset
.
#include "thsq.h"
/*---------------------------------------------------------------------------*/
static void
callback_thsq(enum thsq_reason r, const char *str, int len)
{
if(r == THSQ_COMMAND && str != NULL) {
if(strncmp(str, "Cset", 4) == 0) {
/* we do something based on this command */
}
}
}
/*---------------------------------------------------------------------------*/
void
app(void)
{
static struct thsq_callback cb;
thsq_add_callback(&cb, callback_thsq);
}
/*---------------------------------------------------------------------------*/
Variables
Just as with commands, the system internally uses variables that must not be used for other purposes. If not followed, the behavior is undefined - both on device firmware level, and may be undefined in the frontends used for the product.
Customer Application Variables
To avoid using the same variable name as a internally used variable, follow the same guideline as with commands. Do start the variable name with capital C
, however there is not a restriction to four letters in this case. Thus, the following are valid customer application variables. Try keeping the variable name short, yet descriptive.
Cpressure
Cmodel
Clat
Clong
Cversion
Also refer to the THSQ_PERIOD
callback reason documented here.