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 Robotics

Arduino Robotics Series, from a car to a robot arm

Arduino keeps standing out from the crowd of all-around development boards due too its ease of use and budget price. As a result, this has enabled almost anyone to get his own idea into life no matter how crazy or even useless to the whole world it was, except for its maker! Also, it has …

Arduino Robot Arm

How to build an Arduino Robot Arm placed on RC Car

Arduino robots are always funny and definitely more enjoyable when combined with robotic arm! And today, I will walk you through the making of a simple Arduino Robot Arm that’s made of cardboard and how you can attach it over your Arduino Bluetooth RC Car / Robot that you have made so far through this series. …

Arduino Line Following Robot

How to build an Arduino Line Following Robot using Cardboard

Arduino Line Following Robot is one of the easiest and most well-known projects that anyone can make to learn the basics of programming, electronics, and mechanics all in one project. It’s known that this project is common for most of the makers and tech students and today I am going to give it a revisit …

Arduino Obstacle Avoiding Robot

How to build an Arduino Obstacle Avoiding Robot using Cardboard

Back again with another Arduino Bluetooth RC Car tutorial but with an advanced feature that makes your car autonomous by adding ultrasonic sensors to the RC Car you have made before!. Yeah, I know that you may have seen other tutorials using ultrasonic to make the car/robot avoid obstacles ahead, but I am going to …

Arduino Bluetooth RC car

How to make an Arduino Bluetooth RC Car using Cardboard

  Cardboard crafts are one of the most popular and easy to make DIY stuff. Mixing this with the unmatchable enjoyment of RC Cars and the ease of using Arduino, I am going to show you how to make a Cardboard Arduino Bluetooth RC car that you can control via Bluetooth from your smartphone.  …

Arduino Security Camera

Arduino Security Camera System (Arduino Home Hacks #4)

Arduino Security Camera Have you ever wanted to check your home in real time? Afraid that maybe someone has stormed in, don’t remember if you shut the door or not or maybe wanna check if your Hyper-energetic dog has broken any of your dishes AGAIN!! 🙂 Then this is the perfect place for you cause today …