Commands are sent to your dotDevice from your ESP32 via WebSockets, using the dotDevice.h header file, to the central EmSys Lab server. Please see the following [here] for an example on how to send a command to your dotDevice from the TinyPico.
The command format is a JSON formatted string with the following format:
{
"device": "<YOUR GROUPS GID>",
"cmd": "<COMMAND YOU WISH TO EXECUTE>",
<COMMAND SPECIFIC ARGUMENTS (CSA)>
}
Where <YOUR GROUP GID> is a unique identifier assigned to your group, you should have received this in an email when your group was first assigned. If you do not know your groups gid please send Shane a message.
Commands are split into two categories: ACTION and CONFIG commands. ACTION commands are used to manipulate how your device is shown on screen, for example, movement or colour; as CONFIG commands are used to alter the internal state of your device, for example, configuring the device internal timer. (See Section "Programming your dotDevice" for more information on CONFIG commands).
The table below contains a list of ACTION commands that you can send to your device in the <COMMAND YOU WISH TO EXECUTE> field. It also contains details on the <COMMAND SPECIFIC ARGUMENTS (CSA)> for each command.
In all the examples we shall use an example gid C0FFEE.
| ACTION Commands | Command Specific Arguments | Example |
|---|---|---|
| SAY | "text" : "<TEXT TO WRITE>" |
{"device":"C0FFEE", "cmd":"SAY", "text": "Hello!"} |
| COLOUR | "colour" : "<HEX COLOUR CODE>" |
{"device":"C0FFEE", "cmd":"COLOUR", "colour": "#FFFFFF"} |
| SIZE | "size" : <SIZE VALUE 0 - 20> |
{"device":"C0FFEE", "cmd":"SIZE", "size": 10} |
| ADJUST_XPOS | "dx" : <CHANGE IN X POSITION> |
{"device":"C0FFEE", "cmd":"ADJUST_XPOS", "dx": 2} |
| ADJUST_YPOS | "dy" : <CHANGE IN Y POSITION> |
{"device":"C0FFEE", "cmd":"ADJUST_YPOS", "dy": 2} |
All the commands above perform a visible action on your dotDevice:
SAYwill cause a text messge to appear above your dotDevice for three seconds.COLOURwill change the colour of your device to the hex colour value provided in the"colour"CSA.SIZEwill change the size of your device, to a maximum size of 20.ADJUST_XPOSwill move the X coordinate position of the dotDevice by the amount specified in the"dx"CSA. Note you cannot move more than +-10 from your initial starting position.ADJUST_YPOSwill move the Y coordinate position of the dotDevice by the amount specified in the"dy"CSA. Note you cannot move more than +-10 from your initial starting position.
The table below contains a list of CONFIG commands, more details on these are specified in the "Programming your dotDevice".
| CONFIG Commands | Command Specific Arguments | Example |
|---|---|---|
| LOAD | - | {"device":"C0FFEE", "cmd":"LOAD"} |
| TIMER_CFG | - | {"device":"C0FFEE", "cmd":"TIMER_CFG"} |
| TIMER_VAL | "value": <MILLISECONDS BETWEEN COMMANDS> |
{"device":"C0FFEE", "cmd":"TIMER_VAL", "value":50} |
| RUN | - | {"device":"C0FFEE", "cmd":"RUN"} |
| HALT | - | {"device":"C0FFEE", "cmd":"HALT"} |
Your dotDevice is programmable, it contains a small amount of memory where 256 ACTION commands can be stored and executed at a regular rate using a built in timer.
Above shows a Finite State Machine (FSM) of your dotDevice. Your device should be initialised to the IDLE state on boot. When your dotDevice is in the IDLE state it can receive ACTION commands and will respond to them accordingly. In the LOAD state ACTION commands are not executed but are saved in the command memory. In the RUNNING state commands are executed at the rate set by the Timer Unit and received ACTION_ commands are executed.
Above is a diagram for the architecture of the dotDevice Command Memory Unit.
The command memory has a write port, where ACTION commands are loaded into the memory, and a read port, where ACTION commands are read from.
Writing commands into the command memory is controlled via the Instruction Loader module, as reading and executing commands is controlled by the Execution Unit. The rate at which the Execution Unit reads and executes commands stored in the command memory is controlled by the Timer Unit. For more information on configuring the Timer Unit see the section "Configuring the dotDevice Timer" below.
The diagram shows two signals at the bottom state==loading and state==running. These two signals indicate that the Instruction Loader unit is only active in the LOADING state and that the Execution Unit is only active in the RUNNING state (see the configuration FSM above).
To load a command sequence into the command memory the device must enter the LOADING state.
Entering the LOADING state can only be a achieved when a device is in the IDLE state and has received the LOAD command.
Whenever a dotDevice enters the LOADING state the write_addr signal is set to zero.
Once the dotDevice is in the LOADING state any ACTION command received will not executed but instead will be placed into the command memory at the location write_addr by the Instruction Loader. Once the command has been written into the command memory the Instruction Loader then increments the write_addr by one, moving it onto the next address.
The only way to leave the LOADING state is to issue a RUN config command. This places the dotDevice in a RUNNING state, where commands are issued from the command memory at a regular interval defined by the Timer Unit ( For details on how to configure the Timer Unit please see the Section Configuring your dotDevice Timer of this datasheet)
While in the RUNNING state the Execution Unit will read the command at address read_addr at every tick of the Timer Unit. It will then execute the action command saved at that address and increment the read_addr by one. If the read_addr signal is the same value as the write_addr signal, then the read_addr is set to zero, restarting the command sequence.
The only way for a device to exit the RUNNING state is to receive a HALT command, which places it back in the IDLE state and the ``command memory``` is cleared.
Assuming the device is initially in the IDLE state and the device name is C0FFEE.
{ "device":"C0FFEE", "cmd":"LOAD" }
{ "device":"C0FFEE", "cmd":"ADJUST_XPOS", "dx": 2 }
{ "device":"C0FFEE", "cmd":"ADJUST_XPOS", "dx": 2 }
{ "device":"C0FFEE", "cmd":"ADJUST_XPOS", "dx": -2 }
{ "device":"C0FFEE", "cmd":"ADJUST_XPOS", "dx": -2 }
{ "device":"C0FFEE", "cmd":"RUN" }
After executing these commands the device is in the RUNNING state, wobbling back and forth. Executing the following command will return the device to the IDLE state where it can be reprogrammed.
{ "device":"C0FFEE", "cmd":"HALT" }
To configure the Timer Unit of your dotDevice you first need to enter the TIMER_CFG state. Once in the TIMER_CFG state it is then possible to issue a TIMER_VAL command, with the period of the timer as a CSA. This then sets the period of the Timer Unit and returns the dotDevice to the IDLE state.