Industry 4.0 library

Intro

The Plug & Sense! Industry 4.0 device supports the most extended industrial protocols. Since it is the responsibility of the customer to choose sensors and integrate them on her Plug & Sense!, Libelium strongly recommends customers to learn to handle properly these sensors before integrating them with the Plug & Sense! node. This involves not only acquiring knowledge related to the sensor, but a deep learn of how the industrial protocols work.

A good basis on how industrial protocol works, like commands, transmission speed, format of the communication packets, etc, will greatly help and improve the integration of the sensors to the platform.

WaspIndustry classes

Each protocol available in the Industry 4.0 device has its own class to manage the functions related to them.

It is mandatory to include the Industry library when using this Plug & Sense!. The following line must be introduced at the beginning of the code:

#include <WaspIndustry.h>

Before connecting the sensors to the Plug & Sense! Industry 4.0 check the "Sensor sockets" section in this guide. Keep in mind that not every protocol is available for every socket.

4-20 mA Current Loop

Industry_4_20 class

Functions:

Public functions	Description
Industry_4_20 (uint8_t _socket)	Class constructor
ON()	Turn on 4-20 mA socket
OFF()	Turn off 4-20 mA socket
read()	Read the 4-20 mA sensor

Class constructor

The 4-20 mA sensors can be connected to sockets B and F. Depending on the socket or sockets used with 4-20 mA sensors, an object will be created in the code for every sensor.

// Instance a new sensor in socket B
Industry_4_20 mySensorB(IND_SOCKET_B);
// Instance a new sensor in socket F
Industry_4_20 mySensorF(IND_SOCKET_F);

Switch socket on

The ON() function prepares the socket to power supply the sensor.

// Turn ON the sensor
mySensor.ON();

Switch socket off

The OFF() function removes the power supply from the socket.

// Turn OFF the sensor
mySensor.OFF();

Sensor reading

The read() function reads the value from the sensor. The value read from the sensor will be stored in an internal variable of the library named _current. Additionally, the function returns the value read as a float.

  // Read the sensor
  mySensor.read();
  // Print value read from sensor
  USB.printFloat(mySensor._current, 3);
  
  float current = mySensor.read();

You can see how to use these functions in this example:

Ind 01: 4-20 mA exampleInd 01: 4-20 mA example

RS-485

Industry485 class

Functions:

Public functions	Description
Industry485(unsigned long baudrate)	Class constructor
ON()	Turn on RS-485 socket
OFF()	Turn off RS-485 socket
receive()	Receives data from the socket
send(const char *s)	Sends data through socket

The Industry485 class inherits methods from the Wasp232 library. For further information and prototypes of the different functions, please check the Wasp232 library in the Waspmote API.

Class constructor

An RS-485 sensor can be connected to socket E. In order to use the methods related to the Industry485 class, an object of that class will be created in the code. The constructor requires a parameter to determine the transmission speed.

// Instantiate Industry485 object
Industry485 sensor485(9600);

Switch socket on

The ON() function prepares the socket to power supply the sensor.

// Turn ON the sensor
mySensor.ON();

Switch socket off

The OFF() function removes the power supply from the socket.

// Turn OFF the sensor
mySensor.OFF();

Power up 12V line

The setPowerSocket() function enables the 12 V power line in the socket. The function requires one parameter, the state of the power line in the socket that will determine whether it is enabled or disabled.

State options:

• SWITCH_ON

• SWITCH_OFF

// Comment this line if the sensor has an external
// power supply
sensorSDI12.setPowerSocket(SWITCH_ON);

Receiving data

The receive() function reads data received from the sensor and returns de number of bytes read. Data is stored in an internal variable of the library named _buffer. This variable is defined as an array of uint8_t so the length of data is stored in _length.

if(mySensor.receive() > 0)
{ 
  USB.println(mySensor._buffer, mySensor._length);
}

Send data

The send() function sends data through the socket. There are several prototypes of this function defined in the Wasp232 library.

// Send data "AUTO" through the 485 socket
mySensor.send("COMMAND\r");

You can see how to use these functions in this example:

Ind 02: RS-485 exampleInd 02: RS-485 example

RS-232

Industry232 class

Functions:

Public functions	Description
Industry232(unsigned long baudrate)	Class constructor
ON()	Turn on RS-232 socket
OFF()	Turn off RS-232 socket
receive()	Receives data from the socket
send(const char *s)	Sends data through socket

The Industry232 class inherits methods from the Wasp232 library. For further information and prototypes of the different functions, please check the Wasp232 library in the Waspmote API.

Class constructor

An RS-232 sensor can be connected to socket E. In order to use the methods related to the Industry232 class, an object of that class will be created in the code. The constructor requires a parameter to determine the transmission speed.

// Instantiate Industry232 object
Industry232 sensor232(9600);

Switch socket on

The ON() function prepares the socket to power supply the sensor.

// Turn ON the sensor
mySensor.ON();

Switch socket off

The OFF() function removes the power supply from the socket.

// Turn OFF the sensor
mySensor.OFF();

Power up 12V line

The setPowerSocket() function enables the 12V power line in the socket. The function requires one parameter, the state of the power line in the socket that will determine whether it is enabled or disabled.

State options:

• SWITCH_ON

• SWITCH_OFF

// Comment this line if the sensor has an external
// power supply
sensorSDI12.setPowerSocket(SWITCH_ON);

Receiving data

The receive() function reads data received from the sensor and returns de number of bytes read. Data is stored in an internal variable of the library named _buffer. This variable is defined as an array of uint8_t so the length of data is stored in _length.

if(mySensor.receive() > 0)
{ 
  USB.println(mySensor._buffer, mySensor._length);
}

Send data

The send() function sends data through the socket. There are several prototypes of this function defined in the Wasp232 library.

// Send data "AUTO" through the 232 socket
mySensor.send("COMMAND\r");

You can see how to use these functions in this example:

Ind 03: RS-232 exampleInd 03: RS-232 example

SDI-12

IndustrySDI12 class

Functions:

Public functions	Description
IndustrySDI12(uint8_t _socket)	Class constructor
ON()	Turn on SDI-12 socket
OFF()	Turn off SDI-12 socket
setPowerSocket(uint8_t _state)	Set 12V power line in socket
available()	Number of characters available
isSensor(char *sensorSearchedName)	Detects if SDI-12 sensor is present
sendCommand(char* cmd, uint8_t length)	Sends data through socket
readCommandAnswer(uint8_t length, unsigned long timeout)	Received data if available

The IndustrySDI12 class inherits methods from the WaspSDI12 library. For further information and prototypes of the different functions, please check the WaspSDI12 library in the Waspmote API.

Class constructor

SDI-12 sensors can be connected to sockets A, B, C and D. In order to use the methods related to the IndustrySDI12 class, an object of that class will be created in the code. The constructor requires a parameter to determine the socket where the sensor is connected.

// Instantiate IndustrySDI12 object
IndustrySDI12 sensorSDI12(IND_SOCKET_A);

Switch socket on

The ON() function prepares the socket to power supply the sensor.

// Turn ON the sensor
mySensor.ON();

Switch socket off

The OFF() function removes the power supply from the socket.

// Turn OFF the sensor
mySensor.OFF();

Power up 12V line

The setPowerSocket() function enables the 12V power line in the socket. The function requires one parameter, the state of the power line in the socket that will determine whether it is enabled or disabled.

State options:

• SWITCH_ON

• SWITCH_OFF

// Comment this line if the sensor has an external
// power supply
sensorSDI12.setPowerSocket(SWITCH_ON);

In SDI-12 sensor sockets, the 12 V power line is enabled automatically when the ON() function is called. If the sensor does not need power supply from the Plug&Sense!, user can disable this power line with the setPowerSocket(SWITCH_OFF) function.

Check sensor connection

The isSensor() function checks if a sensor is connected in the socket. The function requires one paramater which is the name of the sensor. The function will check internally if the name read from the sensor is the same as the parameter.

The function uses internally two variables available for the user. The address of the sensor which is stored in the address variable, and the serial number of the sensor that is stored in the serialNumber variable.

// The isSensor function returns 1 if the sensor is present and 0 if not
if(mySensor.isSensor("MySensor name"))
{
    USB.println(F("Sensor found!"));
    USB.print(F("Sensor address: "));
    USB.println(mySensor.address);
    USB.print(F("Sensor serial number: "));
    USB.println(mySensor.serialNumber);
}

Send command

The sendCommand() function sends a command to the sensor. This function requires two parameters, the command to be sent and the length of this command.

Some of the SDI-12 protocol commands can be found in the SDI-12 section in the "Industry 4.0 Protocols" page of this guide. For a complete description of these commands, please check the official site here: SDI-12.

// Send address query command to the sensor
char command[] = "?!";
mySensor.SendCommand(command,strlen(command));

Read answer

The readCommandAnswer() function waits until time is out for a determined number of bytes. The function requires 2 parameters. The first one is the amount of bytes expected from the sensor. The second one is the time to wait for data response.

uint32_t timeout = 10000;
uint8_t response_length = 15;

// Expecting a 15 byte length response for 10 seconds
sensorSDI12.readCommandAnswer(response_length, timeout);

You can see how to use these functions in this example:

Ind 04: SDI-12 exampleInd 04: SDI-12 example

Modbus

Modbus class

Functions:

Public function	Description
IndustryModbus(uint8_t _socket, uint8_t _sensorAddr)	Class constructor
ON()	Turn on Modbus socket
OFF()	Turn off Modbus socket
setPowerSocket(uint8_t _state)	Set 12V power line in socket
setBaudrate(unsigned long baudrate)	Set transmission speed
read(uint16_t _registerAddr, uint16_t _numOfRegisters)	Read sensor registers

The IndustryModbus class inherits methods from the ModbusMaster library. For further information and prototypes of the different functions, please check the ModbusMaster library in the Waspmote API.

Depending on the sensor it might be necessary different reading functions. For extended functionalities refer to the Modbus Networking Guide.

Class constructor

Modbus sensors can be connected to sockets E and F. In order to use the methods related to the IndustryModbus class, an object of that class will be created in the code. The constructor requires two parameters to determine the socket where the sensor is connected and the address of the sensor.

Keep in mind that being both Modbus, in socket E the sensor must be Modbus controlled over RS-485 and in socket F sensor must be Modbus controlled over RS-232. Modbus is a software layer, the physical layer will determine to which socket the sensor can be connected to.

// Instantiate IndustryModbus object
// Modbus over RS-485 in address 0x11
IndustryModbus mySensor(IND_SOCKET_E, 0x11);

Switch socket on

The ON() function prepares the socket to power supply the sensor.

// Turn ON the sensor
mySensor.ON();

Switch socket off

The OFF() function removes the power supply from the socket.

// Turn OFF the sensor
mySensor.OFF();

Power up 12V line

The setPowerSocket() function enables the 12V power line in the socket. The function requires one parameter, the state of the power line in the socket that will determine whether it is enabled or disabled.

State options:

• SWITCH_ON

• SWITCH_OFF

// Comment this line if the sensor has an external
// power supply
sensorSDI12.setPowerSocket(SWITCH_ON);

Change transmission speed

The setBaudrate() function changes the data transmission speed. This function requires one parameter which is the working baud rate of the sensor. The baud rate is stored in the internal variable of the library baudrate.

By default, most sensors use a baud rate of 9600 bps (bits per second). If this function is not used in the code, the platform will set this default baud rate.

// Set baud rate at 14200 bps
sensorSDI12.setBaudrate(14200);

Read data from the sensor

The read() function sends a read holding registers request to the sensor, which will respond with sensor data stored in those registers. The library internally manages all this communication process and stores data in the internal variable response, defined as an uint16_t array (uint16_t response[64]).

Most of the sensor readings of sensors available on the Libelium Catalog are done by this very same function. For extended functionalities of the Modbus protocol, please refer to the Modbus Networking Guide and to the Modbus Master library in the Waspmote API.

// Read data from sensor in register address 0x00
// Data requested length 4 registers
mySensor.read(0x00, 0x04);

USB.print("Data in first register: ");
USB.println(mySensor.response[0]);
USB.print("Data in second register: ");
USB.println(mySensor.response[1]);
USB.print("Data in third register: ");
USB.println(mySensor.response[2]);
USB.print("Data in fourth register: ");
USB.println(mySensor.response[3]);

You can see how to use these functions in this example:

Ind 05: Modbus exampleInd 05: Modbus example