Using RIOTOUS

RIOTOUS has been designed with simplicity at its heart keeping the number of user functions lower than 20 (with some of those functions being slight variations of each other). The main functions to the user are given below.

 

Command Responses

Command related functions return the following

Response

Value (Unsigned char)

Command In progress

0

Command Success

1

Command Fail

2

Command Error

3

Command Timeout

4

 

void riotous_init(void)

This is the first function that is called after the microcontroller has been configured. This function, when called, will configure the UART module, clear data arrays, set control variables, and send a few commands to the ESP8266 (such as disabling echoing).

 

unsigned char riotous_timeoutStatus(void)

Earlier version of RIOTOUS had issues with “keep alive” signals. This function returns true if the server has requested a confirmation that the device is still connected. If no response is made within 10 seconds, the connection will be closed by the server.

 

void riotous_sendPing(void)

Call this function when riotous_timeoutStatus() returns true.

 

unsigned char riotous_probe(void)

While not entirely important, this function can be used to check if the ESP8266 module is functioning correctly. When called, RIOTOUS will send an AT command to see if the module responds with OK. This function is a command function and returns a command response.

 

unsigned char riotous_connectToWiFi(unsigned char *SSID, unsigned char *PASS)

This function will connect to the WiFi network whose SSID is equal to the string SSID and use the network key PASS. The strings passed to this function must be 0 terminated but the easiest way to use this function is to write a string into this function. This function is a command function and returns a command response.

 

unsigned char riotous_connectToServer(unsigned char *IP, unsigned char *PORT)

This function will connect the ESP8266 module to a server whose IP is the string IP and port is the string PORT. Both these strings are zero terminated and C strings are sufficient for this function. This function is a command function and returns a command response.

 

unsigned char riotous_connectToRiotServerEncrypted( const char *IP, const char *PORT, const char *username, const uint32_t *ekey)

This function will connect the ESP8266 module to a RIOTOUS server whose IP is the string IP and port is the string PORT. The function will also need a valid username for the connecting device and a 32-bit x 4 array symmetric key that is registered on the server. This function is a command function and returns a command response.

 

unsigned char riotous_connectToRiotServer(unsigned char *IP, unsigned char *PORT)

This function will connect the ESP8266 module to a RIOTOUS server whose IP is the string IP and port is the string PORT. Both these strings are zero terminated and C strings are sufficient for this function. This function is a command function and returns a command response.

 

unsigned char riotous_sendData(unsigned char *sendBuff, unsigned char length)

This function sends the data found in the array sendBuff whose size is defined by length. If a generic data buffer is used, be careful if using sizeof() in place of length as the data put into that buffer may be small in size than the array itself. This function is a command function and returns a command response.

 

unsigned char riotous_sendDataRiotous( unsigned char *sendBuff, unsigned char length, const char dataType)

This function sends data found in the array sendBuff whose size is defined by length (max length is 8 bytes). As opposed to sending just the data found in the array, the data is sent using the basic RIOTOUS data protocol which is required if communicating with a RIOTOUS server. In most cases, only the TYPE_DATA needs to be used but the reroute type may also be useful for client to client communication. The function also requires a datatype which is shown in the table below. This function is a command function and returns a command response.

Data Type Value Comments
Data for server TYPE_DATA Use when sending data to server
Reroute Data to ID TYPE_REROUTE Use when sending data to other client connected to server
Set user ID TYPE_ID Set the ID of the connected device
Set username TYPE_USER Do not use (automatically handled)
Encrypted data TYPE_ECRYPT Do not use (automatically handled)
Alive Ping TYPE_ALIVE Do not use (automatically handled)
Encrpyt Solution TYPE_SOLUTION Do not use (automatically handled)

 

unsigned char riotous_getCommandStatus(void)

This function returns the current state of a command currently being executed. If, for example, riotous_connectToWiFi has been called and the module is in the process of connecting to the network, this function would return 0 (command in progress).

 

unsigned char riotous_wifiStatus(void)

This function returns the current status of the WiFi connection. If a WiFi connection has been established then true (1) is returned, else false (0).

 

unsigned char riotous_serverStatus(void)

This function returns the current status of the server connection. If a server connection has been established then true (1) is returned, else false (0).

 

unsigned char riotous_dataStatus(void)

This function returns the current state of the data engine. If there is data in the data buffer that is complete (a complete proper packet), and it has not be dealt with then this function returns true (1), else false (0). Once called, this will return false.

 

unsigned char *riotous_dataBufferPtr(void)

This function returns a pointer that points to the RIOTOUS data buffer. To ensure that RIOTOUS functions correctly, copy data from the RIOTOUS buffer into your own array buffer immediately or use the data in this buffer as soon as possible as new incoming data will override the data currently stored.

 

unsigned char riotous_dataLength(void)

This function returns the length of the data in the RIOTOUS data buffer.