Pulga Control Application - EyesOfThings/Software GitHub Wiki

Index

  1. Introduction
  2. API (MQTT Restricted Topics)
  3. Screenshots of using the application
  4. Limitations
  5. Dependencies
  6. Additional information

Introduction

Pulga, which means flea in Spanish, is the proposed tiny MQTT broker implementation for EoT devices. Its name derives from Mosquitto, which is a widely-used Open Source MQTT v3.1 message broker written by Roger Light. As opposed to Mosquitto, Pulga is a lightweight broker designed to be run in embedded systems. While Mosquitto requires at least 3MB RAM, Pulga has been tested using only 512KB and probably can still run using less memory.

images/pulga.png

To develop Pulga it was necessary to start from the ground-up implementing only the minimal parts of the protocol. It uses the MQTTPacket library of the Eclipse Paho MQTT C/C++ client library for embedded platforms. This library contains the lowest level C library which supplies simple serialization/deserialization routines depending on the type of message sent/received.

Functionality

In particular, Pulga has the following MQTT protocol functionality implemented:

  1. Manage connection/disconnection of a client.
  2. Publish message.
  3. Multiple clients can connect to Pulga and subscribe/unsubscribe to topics.
  4. Topics/subscriptions management. Currently Pulga does not consider hierarchical topics (subtopics), only basic topics.
  5. Keep alive functionality through the ping request.

With respect to other typical features of a MQTT broker as defined by the protocol, there are some of them that are not implemented because of the main focus of Pulga broker. More specifically Pulga does not manage retained messages, the definition of a session as clean or durable, or the “last will” option, which allows a client to send a message that it wishes the broker to forward when it disconnects unexpectedly.

Additional functionality

As used in EoT, Pulga includes other functionality that a typical MQTT broker does not have. The most important is that it adds the possibility of defining 'restricted' topics. This option allows to include new uses for the MQTT broker. When a Publish message is received, Pulga first detects if the topic is a 'restricted' one using a simple parser on the broker, changing the typical publish behaviour as the programmer defines. This approach allows the user to have additional functionality:

  • Send/receive files. Considering that the MQTT protocol sends binary messages (the text of an MQTT message is always serialized) it is possible to use an MQTT message to send binary data without serializing/deserializing it. This process would allow us to upload the applications we want to run into the device or send the captured images in the EoT device to a client that requests them.
  • Configuration of the EoT device. By defining different configuration topics, Pulga is able to manage the different EoT parameters and to configure the WiFi connection of the device. A simple parser is used to manage the messages published.
  • Configuration of access to a WiFi infrastructure. The configuration device can send the required connection data to the EoT device. This data can be stored in the device and used by preloaded applications to connect to an existing WiFi.

QoS levels

Moreover MQTT defines three levels of Quality of Service (QoS). The QoS defines how hard the broker/client will try to ensure that a message is received. There are three levels of QoS defined by the MQTT protocol:

  1. The broker/client will deliver the message once, with no confirmation.
  2. The broker/client will deliver the message at least once, with confirmation required.
  3. The broker/client will deliver the message exactly once by using a four step handshake.

The current Quality of Service (QoS) implemented in Pulga is the QoS 1.

Control mode

The control mode, which will be activated through a dip switch, will receive and respond to this control commands:

  • Establish wireless communication.
  • Change from AP mode to Station Mode and connect to another existing AP.
  • Upload and flash an application (a payload).
  • Upload data to SD card in EoT.
  • Run application (payload).
  • Download data from SD card in EoT.
  • Change network password.
  • Remove network password.
  • Request a camera snapshot.
  • Update Myriad’s clock/time with the client’s clock/time (clock/time is strictly needed, for example to store timestamps on events).

As a way to test communications, the interpreter will be on when in AP mode (and off when in station mode), and flashing upon receiving every command. The SD Card will be used to store application data (audio files, cascade classifier data...), configuration parameters, snapshots, application results, etc.

Pulga will be always resident in the device Flash. The application to run will be stored also in the Flash. If for some reason the payload does not work properly then the device will have to be booted in Control mode to flash another payload. If for some reason the module stops working then the device will have to be connected to a PC (with the JTAG cable) and Pulga will have to be reflashed.

API (MQTT Restricted Topics)

When a message is received by Pulga in one these topics, the behavior of the broker changes from a typical MQTT broker. The client must subscribe to each reserved topic before sending the first message. The unsubscribing is managed afterwards automatically by the broker after finishing the command, so it is not necessary for the client to send the unsubscribe command.

Some of the reserved topic must answer to the client if the operation has been performed correctly in the same reserved topic. In case that an error occurs, Pulga will send “-1” to the client. Otherwise, it will send “0”. The package described corresponds to a packet of information with a maximum size of 1024 bytes. This fact is because of the limitation imposed by the CC3100 WiFi device when receiving a message through sockets.

Screenshots of using the application

The main screenshots of the application can be seen below:

  • Pulga starts

images/pulga_starts.png

  • Topic subscription:

images/pulga_topicSubscription.png

  • Create Access Point:

images/pulga_createAP.png

  • Update date of EoT device:

images/pulga_updateEoTdevice.png

Limitations

  • There is a simple version of Pulga (only MQTT broker) which includes the possibility of sending a snapshot from the camera installed on the initial prototype of the EoT device board. This is not yet implemented in the last version until the NanEye camera is included in the board.
  • The CC3100 has a limitation of receiving a maximum of 1472 bytes in a socket. Pulga splits every file/binary it needs to send. We selected a maximum chunk size of 1024 bytes, including at the end 6 bytes which will include the number of the package sent. This has been tested with files and pictures of 4MB at the moment.
  • Memory problems: in custom.ldscript, the parameter _RAM_SIZE_LOS must be configured as the maximum size of a file expected to be received. It can be improved in future versions of Pulga by saving the file not at the end of reception, but when each part is received.
  • Topic EOTUploadElf is not implemented because in the initial hardware prototype there are known conflicts between the SPI of the WiFi chip and the flash memory. Currently this topic works receiving the file and saving it in a folder called Flash in the SD card.

Dependencies

  • Crypto
  • SDCardIO
  • FlashIO
  • WifiFunctions
  • TimeFunctions
  • Camera

Additional information