3. Rover Software: roverapp¶

3.1. What is roverapp?¶

Roverapp is an open-source C/C++ project for single board Linux computers (Raspberry Pi), especially designed for rover. It features multi-threaded schedulable and traceable software under GNU/Linux environment. For multi-threading, POSIX threads (Pthreads) and its synchronization implementations such as mutexes are widely used.

Roverapp complete feature list is given below:

Multi-threaded, schedulable and traceable embedded software.
Cloud communication to Hono 0.5-M9 infrastructure using REST API, using customly created hono_interaction library.
Utilized drivers for Linux modules such as bluetooth (bluetooth-dev).
I2C drivers and applications (threads) for OLED display, SRF02 ultrasonic sensor, HMC5883L magnetometer, GY-521Y accelerometer, etc.
Temperature and humidity measurement using DHT22 sensor.
Reactive implementations for TCP socket server and TCP socket client, with proper JSON formatted data for communication.
OLED display application that is able to display bluetooth, Hono cloud, ethernet, wireless interface, and internet with the help of status_library library.
OpenCV 2.4.9 utilization and image processing application (currently Traffic cone detection).
SHARP Analog Proximity measurement sensor interfacing and implementations.
SRF-02, HCSR-04, and Grove Ultrasonic sensor interfacing and implementations.
Motor driving implementations.
Timing measurement implementations with the help of timing library.
CPU core utilization measurement implementation.
Adaptive Cruise Control behavior implementation.
Parking behavior implementation.
Booth mode implementations.
Implementations for bluetooth-based driving from Android phones.

3.2. roverapp Infrastructure¶

../roverstatic/images/roverapp_infra.png

3.3. Downloading roverapp¶

Note

Rover-app source code is maintained under the following repository:

https://github.com/app4mc-rover/rover-app

3.4. Getting started with roverapp¶

3.4.1. Installation¶

Note

In order to see how roverapp is installed and compiled, please see roverapp Installation section.

3.4.2. Running roverapp¶

After installation, roverapp can be run by the following command from project root:

1	sudo ./roverapp

3.5. roverapp Complete Reference¶

3.5.1. Drivers¶

3.5.1.1. OLED Libraries¶

3.5.2. Created Libraries¶

3.5.2.1. status_library¶

3.5.2.2. hono_interaction¶

The current release covers communication with Eclipse Hono version 0.5-M9.

3.5.2.2.1. Registering a Device¶

3.5.2.2.1.1. Arguments¶

In order to register a device to the Eclipse Hono instance, registerDeviceToHonoInstance should be used. This function is defined as follows:

int registerDeviceToHonoInstance (char * host_name, int port, char * tenant_name, char * device_id)

The function takes the following arguments:

Host name to connect (char *)
Port to connect (int)
Tenant name (char *)
Device ID (char *)

3.5.2.2.1.2. Operation¶

This function constructs a curl call on the system by constructing a string such as the following:

curl -X POST -i -H 'Content-Type: application/json' -d '{"device-id": "4711"}' http://idial.institute:28080/registration/DEFAULT_TENANT

Afterwards, returning pipe content is read and parsed to decide whether the call is accepted or what kind of error has occurred.

3.5.2.2.2. Sending Telemetry Data to Eclipse Hono Instance¶

3.5.2.2.2.1. Arguments¶

In order to send telemetry data to the Eclipse Hono instance, sendTelemetryDataToHonoInstance should be used. This function is defined as follows:

int sendTelemetryDataToHonoInstance (char * host_name, int port, char * tenant_name, char * device_id, char * user, char * password, char * field, double value)

The function takes the following arguments:

Host name to connect (char *)
Port to connect (int)
Tenant name (char *)
Device ID (char *)
Username (char *)
Password (char *)
Field name (char *)
Value (double)

3.5.2.2.2.2. Operation¶

This function constructs a curl call on the system by constructing a string such as the following:

curl -X POST -i -u sensor1@DEFAULT_TENANT:hono-secret -H 'Content-Type: application/json' --data-binary '{"temp": 5}' http://idial.institute:8080/telemetry

Afterwards, returning pipe content is read and parsed to decide whether the call is accepted or what kind of error has occurred.

3.5.2.2.3. Sending Event Data to Eclipse Hono Instance¶

3.5.2.2.3.1. Arguments¶

In order to send event data to the Eclipse Hono instance, sendEventDataToHonoInstance should be used. This function is defined as follows:

int sendEventDataToHonoInstance (char * host_name, int port, char * tenant_name, char * device_id, char * user, char * password, char * field, double value)

The function takes the following arguments:

Host name to connect (char *)
Port to connect (int)
Tenant name (char *)
Device ID (char *)
Username (char *)
Password (char *)
Field name (char *)
Value (double)

3.5.2.2.3.2. Operation¶

This function constructs a curl call on the system by constructing a string such as the following:

curl -X POST -i -u sensor1@DEFAULT_TENANT:hono-secret -H 'Content-Type: application/json' --data-binary '{"temp": 5}' http://idial.institute:8080/event

Afterwards, returning pipe content is read and parsed to decide whether the call is accepted or what kind of error has occurred.

3.5.2.2.4. Handling REST API /HTTP Responses and Status Codes¶

In order to handle the response codes of HTTP requests, handleCode function is developed:

     int handleCode(int code)

The commonly occuring HTTP responses are parsed and displayed in this library within handleCode function.

Error Code	Meaning	Status	Explanation in Hono Terminology
200	OK	1	Device registration is successful
201	Created	1	Device registration is successful
202	Accepted	1	Telemetry data is accepted at Hono instance
200..209		1
400	Bad Request	0
403	Forbidden	0
409	Conflict	0	Device is already registered
400..409		0
503	Service Unavailable	0	There is no consumer running. Please create a consumer

In the library, the meanings of commonlu occurring error codes are considered and status codes are generated. Status or exit code is what the functions in this library returns as an integer.

The following (non-UNIX) convention is adapted:

1 → Successful exit
0 → Non-successful exit

The status value can be used to check if functions succeed. Please see Example Usage section.

3.5.2.2.5. Debugging¶

The header file of the library contains two compiler directives for easy debugging of console output.

#define DEBUG_HTTP_RESPONSE 1
#define DEBUG_DEVICE_REGISTRATION 1

One can either define or comment/undefine these compiler directives. The first compiler directive is used for displaying the strings on console such as:

Constructed curl command
Parsed HTTP response code
The entire pipe that is returned

The second compiler directive is used for displaying the same information, but only in the device registration function. Ideally, since device is registered only once but the data is send constantly, it is advised to see this information at the device registration function, but not for the other functions, to prevent the console overhead. Due to the aforementioned reason, it is advised to keep this part as follows:

//#define DEBUG_HTTP_RESPONSE 1
#define DEBUG_DEVICE_REGISTRATION 1

But uncomment the first line only when it is suspected that something regarding cloud connection is failing.

When there is no internet connection with DEBUG_HTTP_RESPONSE defined, a message such as the following is displayed: Code: 0.

3.5.2.2.6. Example Usage¶

#include <stdio.h>
#include <stdlib.h>
#include "hono_interaction.h"
int main ()
{
          int status;
          double bearing_val;
          status = registerDeviceToHonoInstance("idial.institute",28080,"DEFAULT_TENANT", "roverBearing");
          if (status == 0)  // If DEBUG_HTTP_RESPONSE is commented, you can manually handle errors by using the status/exit code
          {
                        fprintf (stderr, "Device is not registered");
          }

          while (1)
          {
                        bearing_val = 0.5001;
                        status = sendTelemetryDataToHonoInstance("idial.institute",8080,"DEFAULT_TENANT", "4711","roverBearing", bearing_shared);
                        if (status == 0)  // If DEBUG_HTTP_RESPONSE is commented, you can manually handle errors by using the status/exit code
                        {
                                  fprintf (stderr, "Data is not sent");
                        }
          }
}

3.5.2.2.7. Resources¶

The material provided for hono_interaction uses Hono API, which is provided here: Hono API.

3. Rover Software: roverapp¶

3.1. What is roverapp?¶

3.2. roverapp Infrastructure¶

3.3. Downloading roverapp¶

3.4. Getting started with roverapp¶

3.4.1. Installation¶

3.4.2. Running roverapp¶

3.5. roverapp Complete Reference¶

3.5.1. Drivers¶

3.5.1.1. OLED Libraries¶

3.5.2. Created Libraries¶

3.5.2.1. status_library¶

3.5.2.2. hono_interaction¶

3.5.2.2.1. Registering a Device¶

3.5.2.2.1.1. Arguments¶

3.5.2.2.1.2. Operation¶

3.5.2.2.2. Sending Telemetry Data to Eclipse Hono Instance¶

3.5.2.2.2.1. Arguments¶

3.5.2.2.2.2. Operation¶

3.5.2.2.3. Sending Event Data to Eclipse Hono Instance¶

3.5.2.2.3.1. Arguments¶

3.5.2.2.3.2. Operation¶

3.5.2.2.4. Handling REST API /HTTP Responses and Status Codes¶

3.5.2.2.5. Debugging¶

3.5.2.2.6. Example Usage¶

3.5.2.2.7. Resources¶

3.5.2.3. pthread_monitoring¶

3.5.2.4. pthread_distribution_lib¶

3.5.2.5. timing¶

3.5.3. Tasks and Threads¶