Loading...
 

Ciao MCU

Introduction

Ciao Library allows you to send and receive data outside the microcontroller, through a serial communication, in a simple and intuitive way. Ciao Library provides three main functions that can be used in your sketch:

  • read(connector)
  • write(connector, param1, param2, param3
  • writeResponse(connector, id, param1, param2, param3)

In addition to those functions, comes in handy CiaoData, which provides utilities functions for manage, extract and manipulate information data.

  • get(index)
  • isError()
  • isEmpty()

In order to use Ciao Library you only need to:

  1. import Ciao Library;
  2. initialize it with the begin() function;

Note: before using Ciao Library you must enable the connectors you're going to use in your sketch, and sometimes configure them. Read  how to enable a connector and the list of connectors to understand how to setup a connector.

read

The read function enables the board to receive data from a connector(examples: xmpp, websocket, twitter). It returns a CiaoData object composed by the id and the data provided by the connector. 
The get function will allow you to retrieve the various field from the CiaoData object (look get Function).

Example

To retrieve data from a xmpp connector, you need to do these simple steps:

#include <Ciao.h>

setup{ 
    Ciao.begin() 
} 
loop{ 
    CiaoData data; 
    data = Ciao.read("xmpp");            // query to xmpp connector   
}

 

write

The write function enables the board to send data to a connector.  It accepts up to 4 parameters, the first is always the connector type we want to interact with,  
while the other parameters may be used freely according to different use cases that can occur.

Example:

Supposing to send data to a xmpp connector, the parameters in the write function will be:

  • first parameter is connector type; 
  • second parameter is destination name; 
  • third parameter is the message to send;
#include <Ciao.h>

setup{ 
    Ciao.begin(); 
} 
loop{ 
    Ciao.write("xmpp","user@xmpp","hello from MCU"); 
}

 

writeResponse

The writeResponse function enables to directly reply to a request sent by a connector. It accepts up to 5 parameters, the first is always the connector type we want to interact with, the second is always the id value we want to send the response, while the other parameters may be used freely according to different  use cases that can occur.

Example:

Supposing to response to a previous xmpp request, the parameters in the writeResponse function will be:

  • first parameter is connector type; 
  • second parameter is id of the xmpp request; 
  • third parameter is the message to send;
#include <Ciao.h>

setup{
    Ciao.begin(); 
} 
loop{

    CiaoData data; 
    data = Ciao.read("xmpp");            // query to xmpp connector     
    String id = data.get(0);         
    String sender = data.get(1); 
    String message = data.get(2);
    Ciao.writeResponse("xmpp",id,"response from MCU");

}

 

get

The get function allow to extract information contained inside CiaoData. This information can be vary according to the connector type used.

The function accept only one parameter that is the position (index) of the data format setted in the connector.

Example

CiaoData for an XMPP connector is usually composed by an id (index "0"), a sender (index "1") and the message (index "2"). 

To extract this information you can follow the below steps:

#include <Ciao.h>

setup{ 
    Ciao.begin() 
} 
loop{ 
    CiaoData data; 
    data = Ciao.read("xmpp");            // query to xmpp connector 
     
    String id = data.get(0);                 // get information from CiaoData 
    String sender = data.get(1); 
    String message = data.get(2);     
}

 

splitString


The splitString function enables the user to manage the MCU command sent by the connector. 
The function accepts up four parameters, the first is the serial command for the MCU, the second parameter is the character that should be used to split the serial command, while the third and fourth parameter are respectively, the array of strings used to split the serial command received and the size of the array itself .

Example

If by a xmpp connector send a command with three parameter, like "digital/13/1", to split the command will need to create a three element string array and after invoke the splitString function, as below:

#include <Ciao.h>

void setup() {
     Ciao.begin();
     Serial.begin(57600);
}

void loop() {
     CiaoData data = Ciao.read("xmpp"); 
     String id = data.get(0);
     String sender = data.get(1);
     String message = data.get(2);
     String command[3];
     splitString(message,"/",command,3); 
     Serial.println("command type: "+command[0])   //output is digital
     Serial.println("pin: "+command[1])                      //output is 13
     Serial.println("pin value: "+command[2]))            //output is 1
}

 

isError

The isError function enables the user to check if the CiaoData object contain an error code. 
The function return the true boolean state if in the CiaoData is present an error code.

Examples

Check if in the data received from the xmpp connectors is present an error code.

#include <Ciao.h>
  
void setup() {
Ciao.begin();
Serial.begin(57600);
}

void loop() {
CiaoData data = Ciao.read("xmpp");   
    if(data.isError()){  
      String message = data.get(2);
      Serial.println(" error:"+ message);
    }
}

isEmpty

The isEmpty function enables the user to check if the CiaoData object is empty. 
The function return the true boolean state if the CiaoData is empty. 

Examples

Extract the information contained in CiaoData object only if the object is not empty.

#include <Ciao.h>
  
void setup() {
Ciao.begin();
    Serial.begin(57600);
}

void loop() {
CiaoData data = Ciao.read("xmpp");   
  if(!data.isEmpty()){  
        String id = data.get(0);
      String sender = data.get(1);
      String message = data.get(2);
      Serial.println("id: "+id);
      Serial.println("sender: "+sender);                      
      Serial.println("message: "+message);         
    }
}