/simple_serial_arduino

A simple library for communication over serial interfaces.

Primary LanguageC++MIT LicenseMIT

Simple Serial

A simple library for communication over serial interfaces. It can be used for microcontroller to microcontroller communication or computer to microcontroller communication.

Currently supported platforms:

  • Arduino / C++
  • Python

This is a repository for the Arduino / C++ version. Find python version at: https://github.com/nplan/simple_serial_python

The library supports simple and efficient transfer of data types:

  • Integer (signed, 32 bit)
  • Floating point (32 bit)
  • Strings

Custom data types can be easily added.

Installation

Add to Arduino IDE

Download the .zip file. Inside Arduino IDE, go to Sketch > Include Library > Add .ZIP Library... and select the downloaded .zip file. To include library in your sketch use #include <SimpleSerial.h>

Include in C++ project

Clone library to your project and include: #include "simple_serial_arduino/src/SimpleSerial.h>

Usage

Data is sent in packets. Each packet has an id in range 0 - 255. The id is used for identifying topic and data type of the packet. The library does not know data type for a certain id. User must keep track of this.

Example:

#include <SimpleSerial.h>

simple_ser = SimpleSerial(&Serial);

void setup() {
  Serial.begin(115200);
}

void loop() {
  // This function must be called inside main loop as frequently as possible.
  simple_ser.loop();
}

// Send some data
simple_ser.send_int(1, 1234);  // Send packet with id 1 containing an integer
simple_ser.send_float(2, 2.345) // Send packet with id 2 containing a float
simple_ser.send(3, "this is a string") // Send packet containing a string

// Receive data
if (simple_ser.available()) {

  // Read a packet from queue of received packets
  SimpleSerial::Packet packet = ss.read();

  // Convert to desired type
  if (packet.id == 123) {
    int val = byte_conversion::bytes_2_int(packet.payload_len, packet.payload)
    // do sth with val
  }
  // Note: there is no way to know the data type of payload.
  // You should use id to keep track of it.
}

How it works?

Before being sent over serial port, data is framed into packets using using special flag bytes:

  • START Byte - Signalling start of packet, default = ASCII 2 STX
  • END Byte - Signalling end of packet, default = ASCII 3 ETX
  • ESC Byte - Inserted prior to payload data byte if it happens to have the same byte value as one of the flag bytes. default = ASCII 1 SOH

A complete packet frame:

BYTE 0 BYTE 1 BYTE 2 BYTES 3 ... N-1 BYTE N
START LEN ID Payload Data Bytes END

Byte 1 LEN indicates the total length of packet in bytes.

When SimpleSerial::send() function is called, the payload is framed into a packet and placed into send queue. Packets from this queue are sent over serial port inside SimpleSerial::send_loop().

Serial port is being monitored for incoming packets using SimpleSerial::read_loop() function. The function reads incoming packet frames byte by byte. When a complete packet frame is received, it is placed into read queue. Packets are retrieved from this queue with function SimpleSerial::read().

The length of send and read queues is set by optional max_queue_len parameter. If a queue is full, packets are discarded (not sent or not received).

Testing

For testing the library you can use TransmissionTest.ino example or implement your own loop using transmission_test.h

Test example is designed to evaluate packets sent from Python version of this library. You can use python3 -m simple_serial.transmission_tester to run the tests.