Skip to content

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.