Arduino IoT Shield Functions Explainer

Arduino IoT

Arduino IoT

Arduino makers …. you can connect your Arduino to MQTT brokers(servers) and launch your IoT with Arduino IoT Shield!

It’s the 1Sheeld IoT shield that will do the job for you. It’s one of the most important but recent Arduino shields in 1Sheeld. Simply, it turns your Arduino into MQTT client where you can publish and subscribe for topics.

So, in this Arduino IoT blog, I will go through all the IoT Shield functions, each with its code and how you can use it.

 

Hardware components required for the Arduino IoT Shield Function Explainer

  • Arduino Uno.
  • 1Sheeld+ board.
  • Arduino USB cable.
  • LED
  • Push button
  • Male-to-female jumper wires.
  • iOS phone with 1Sheeld App installed on it. That’s because Arduino IoT Shield is supported by 1Sheeld iOS App only.

 

Getting Started

First of all, I recommend you go through this Getting Started Tutorial if this is your first time working with 1Sheeld.

Furthermore, you should have an MQTT broker. So, you can go through this MQTT blog to create your own MQTT broker instance with credentials necessary for this blog. I have used CloudMQTT broker:

Hardware Connection

Just connect the Arduino with your 1Sheeld+ board like this:

Code

Below is the code handling most of the methods provided by the Arduino IoT Shield functions:

That code simply does 3 things:

  • Firstly, publish the message “ready” on the topic “arduino/state” once the Arduino is connected to the broker.
  • Then, use the push button to publish its status “pressed/released” on the topic “arduino/button”.
  • And subscribe on the topic “arduino/led” to turn the LED “on/off”

 

And once you connect your 1Sheeld to the phone and select IoT shield from the App, reset your Arduino. Hence, you will see the connection indicator red circle goes into a green.

Of course, that means the Arduino has connected to the broker successfully.

In addition, you can open the WebSocket UI window and monitor all publish operations your Arduino make and send messages manually to the Arduino subscribed topics, like this:

 

Functions Classifications

I will go through this blog by quoting from the code example above.

Moreover, I will be classifying functions into 3 groups:

  • Firstly: understand the functions responsible for the connection establishment.
  • Then I will move to those responsible for publishing, subscribing for topics’ messages.
  • Finally, it’s important to monitor your code behavior and report all error types. And this will be the last type of functions you are going to learn.

 

A. Connection Establishment Functions

1- void disconnect(void)

Description:

  • It disconnects the Arduino from the broker. Calling it before making a new connection ensures a clean connection. In a typical scenario like resetting the Arduino, the broker might consider that this client “Arduino” is still connected and refuses this new connection after resetting. So, it’s advisable to call the disconnect function at the top of void setup().

Input:

  • Nothing.

Return:

  • Nothing

Example:

  • Written inside void setup() {} function like this:

 

2- void resetConnectionParametersToDefaults(void)

Description:

  • Calling this function resets all parameters to default. It’s called when you disconnect from the broker and want to connect again. So, you are ensuring what parameters are actually holding.
  • Default parameters values already set by the application:
    – Port: 1883.
    – Client ID: IMEI of your smartphone.
    – Clean session: true.
    – Keep-Alive: 60 seconds.
    – Auto Reconnect: true.
    – SSL connection: false.

Inputs by order:

  • Nothing.

Return:

  • Nothing.

Example:

  • Written inside void setup() {} function like this:

 

3- void connect(const char *,const char *,const char *,unsigned int)

Description:

  • It connects your Arduino to a broker with credentials: username, password, and port number.

Inputs by order:

  • Const char array holding broker server.
  • Const char array holding broker given username.
  • Const char array holding broker given password.
  • Unsigned integer holding broker given port number.

Return:

  • Nothing.

Example:

  • Called with the “IoT” Class inside void setup() {} function like this:

 

4- void connect(String, String, String, unsigned int)

Description:

  • Has the same functionality as the above function, but with String objects as inputs.

Inputs by order:

  • String object holding broker server.
  • String object holding broker given username.
  • String object holding broker given password.
  • Unsigned nteger holding broker given port number.

Return:

  • Nothing.

Example:

  • Written inside void setup() {} function like this:

 

 

B. Publishing/Subscribing Functions

1- void publish(const char *,const char *,byte=0,
bool=false)

Description:

  • Publishes char array to the specified topic.

Inputs in order:

  • Const char array holding the topic.
  • Const char array holding payload (message).
  • Byte holding QOS (quality of service). You can enter QOS_0, QOS_1 or QOS_2 (default = QOS_0).
  • Boolean holding Yes ‘true’ or No ‘false’ for retaining message.(default = false)

Return:

  • Nothing.

Example:

  • Called with the “IoT” Class anywhere, like this:

Note: you can use other void publish functions that has different input variables types, like:

– void publish(String,String,byte=0,bool=false)

– void publish(const char *,int,byte=0,bool=false)

– void publish(String,int,byte=0,bool=false)

– void publish(const char *,float,byte=0,bool=false)

– void publish(String,float,byte=0,bool=false)

The choice here depends on 2 parameters:

  • Topic type: char array or string object.
  • Message “payload” type: you want to publish an int, float, string, char array.

2- void subscribe(const char *,byte=0)

Description:

  • Subscribe to the specified topic.

Inputs in order:

  • Const char array holding the topic.
  • Byte holding QOS (quality of service). You can enter QOS_0, QOS_1 or QOS_2 (default = QOS_0).

Return:

  • Nothing.

Example:

  • Called with the “IoT” Class anywhere ( better in void setup() ), like this:

Note: you can another void subscribe function that has different input variable type:

– void subscribe(String,byte=0)

Similarly, like the publish one, the choice here depends on:

  • Topic type: char array or string object.

3- void unsubscribe(const char *)

Description:

  • Unsubscribe to the specified topic.

Inputs:

  • Const char array holding the topic.

Return:

  • Nothing.

Example:

  • Called with the “IoT” Class anywhere, like this:

Note: you can another void unsubscribe function that has different input variable type:

– void subscribe(String)

The choice here depends on:

  • Topic type: char array or string object.

4- void unsubscribe(void)

Description:

  • Unsubscribe to all topics.

Inputs:

  • Nothing.

Return:

  • Nothing.

Example:

  • Called with the “IoT” Class anywhere, like this:

 

5- void setOnNewMessage(void (userFunction)(char *,char *,byte,bool))

Description:

  • Sets a user-defined function to be called when any message is received on any subscribed topic.

Input:

  • The physical address of your created function in the memory that will be called automatically once new data received to execute its functionality.

Return:

  • Nothing.

Example:

  • Called with the “IoT” Class inside void setup() {} function like this:

Note: you can use other setOnNewMessage functions that allow you also to call other user-defined functions but has different input variables types, like:

– void setOnNewMessage(void (userFunction)(String,String,byte,bool))

– void setOnNewMessage(void (userFunction)(char *,int,byte,bool))

– void setOnNewMessage(void (userFunction)(String,int,byte,bool))

– void setOnNewMessage(void (userFunction)(char *,float,byte,bool))

– void setOnNewMessage(void (userFunction)(String,float,byte,bool))

The choice here depends on 2 parameters:

  • Topic type: char array or string object.
  • Message “payload” type: you are expecting to receive an int, float string, char array.

 

 

C. Status & Error Handling Functions

1- void setOnConnectionStatusChange(void (userFunction)(byte))

Description:

  • Sets a user-defined function to be called once a new connection status received.

Input:

  • The physical address of your created function in the memory that will be called automatically once new connection status received to execute its functionality.

Return:

  • Nothing.

Example:

  • Called with the “IoT” Class inside void setup() {} function like this:

In fact, the “statusCode” variable is just a number that’s represented as a literal. Therefor, it makes it easy to understand its meaning.

Furthermore, the “void connectionFunction(byte statusCode)” function you have coded should tell you on the Terminal Shield what is the status of your connection by checking the literal variable.

LITERALS are:

CONNECTION_SUCCESSFUL
CONNECTION_FAILED
CONNECTION_LOST
CONNECTION_LOST_RECONNECTING
NOT_CONNECTED_YET
MISSING_HOST

2- void setOnError(void (userFunction)(byte)

Description:

  • Sets a user-defined function to be called once an error occurs.

Input:

  • The physical address of your created function in the memory that will be called automatically once an error occurs.

Return:

  • Nothing

Example:

  • Called with the “IoT” Class inside void setup() {} function like this:

Again, the “errorCode” variable is just a number that’s represented as a literal. Consequently, this makes it easy to understand its meaning.

So,  the “void error(byte errorCode)” function you have coded should tell you on the Terminal Shield the error type by checking the literal variable.

LITERALS are:

CONNECTION_REFUSED
ILLEGAL_MESSAGE_RECEIVED
DROPPING_OUT_GOING_MESSAGE
ENCODER_NOT_READY
INVALID_CONNACK_RECEIVED
NO_CONNACK_RECEIVED
CONNACK_UNACCEPTABLEP_ROTOCOLVERSION
CONNACK_IDENTIFIER_REJECTED
CONNACK_SERVER_UNAVAILABLE
CONNACK_AUTHENTICATION_FAILED
CONNACK_NOT_AUTHORIZED
CONNACK_RESERVED

 

Conclusion …

I have just covered the most commonly used functions in the Arduino IoT Shield that 1Sheeld has. Surely, there are many other functions in the Arduino IoT Shield available for you to use according to your need.

If you like to go through making Arduino IoT projects, you can see these useful tutorials

 

Finally .. if you have any question, please let me know in the comments below 🙂




Related Blogs

Arduino Temperature Humidity System

IoT Arduino Temperature and Humidity System

Monitor my home environmental parameters remotely is one of the most desirable things I have ever wanted to make. It’s not about purchasing such a system that can get the job done for me. But, passion to create it myself. So, today, I am going to connect the popular DHT sensor to an online MQTT …

Arduino Door Lock

IoT Arduino Door Lock using 1Sheeld and Smartphone

  “Oh God! … It seems like I have forgotten the door lock open, again” … the normal saying whenever I am in hurry to go out! Have you encountered this problem before? It always confuses me since I may even think that I have left the door lock opened, and once I go back, …

IoT Fan Control

Arduino IoT Fan Control using 1Sheeld and Smartphone

Here I am with another IoT-based home automation project; Arduino IoT Fan Control. Every day, I get back from work tired and feeling hot. No air conditioner here and the fan takes much time to start cooling the room, sadly! So, I was thinking why not controlling the fan from outside my home with my …

Arduino Light Control

IoT Arduino Light Control using 1Sheeld and Smartphone

Have you ever forgotten to turn your home lights off when you got outside? Sadly, it happens to me all the time. And this causes confusion once I get my bills! Furthermore, here is one secret about me; I am a lazy man. I always want to control my room lamp from my sweet bed. …

mqtt-protocol

MQTT Protocol – How it Works

MQTT is one of the most commonly used protocols in IoT projects. It stands for Message Queuing Telemetry Transport. In addition, it is designed as a lightweight messaging protocol that uses publish/subscribe operations to exchange data between clients and the server. Furthermore, its small size, low power usage, minimized data packets and ease of implementation …

IoT

IoT: Understanding the Concepts

Actually, that’s not a phrase from the Terminator movies, it’s just the reality of nowadays! Statistics show that the number of connected devices in 2018 are 23+ billion. This is almost 3 times the population density of the Earth, which is 7.6 billion at the time of writing this blog. Furthermore, this number is increasing …