Published January 27, 2022 © GPL3+

Custom UART Protocol on ESP32

Use OSCUP in your project to speedup the development of a custom UART communication! It is an entirely customizable protocol

IntermediateProtip3 minutes4,188

Things used in this project

Hardware components

Espressif ESP32S

Software apps and online services

Arduino IDE

Story

Description

OSCUP is an open source UART protocolo designed for working with ESP32 ARM Processors. The code well documented helps to figure out how to implement a custom protocol on UART port. With this protocol you can transmit and receive data which are tracked by a fixed preamble. It implements ACK and NACK for each packet sent, for managing errors or lost packets.

How it Works

It relies on primitive libraries provided by Espressiff, such as /device/uart.h for interfacing with the low level hardware and functions. The protocol provides two function write and read for sending and receiving data. When you create a new Oscup object you need to pass it an ID which keeps track of the device who sent the packet. Optionally the Oscup object can be istantiated specifying the UART port and the correlated UART TX pin and UART RX pin. By default the communication takes place on UART 0, or rather the USB port.

In fact, it is possible to use OSCUP for a communication between a computer and an ESP32, or between two ESP32.

Commands

Every time the protocol writes data on UART, it inserts a command inside the packet. The command is mandatory, otherwise you may ask yourself why you want to use a protocol (just use arduino Serial). On the reciever, obviously, you must distinguish between the commands you recieve. There are avaialble 4 main commands:

SHARE: this command indicates that the sender just want to share this data with the receiver (for minor reasons). You can use it if you just want to print data on the other device.
CONFIRM: this command indicates that the data that will be sent are a consequence of an action (for example, we pressed a button on device 1, we send data to device 2 and we want that device 2 not only print this data but also store them).
ACK: It is used to tell the sender that the receiver has received the packet
NACK: It is used to tell the sender that the receiver hasn't received the packet; the sender will try to send it again Obviously, you can configure the action you prefer to undertake each command. We suggest not to use ACK and NACK, as for the other two, the previous indications are only guidelines that we have defined for using those two commands. Also, you can configure new commands on arduino (command = uint8_t) and send them directly in the write function

Public Functions

begin: initializes the UART parameters and forwards it to the control hardware. It is mandatory to call it inside void setup(). It takes the baudrate as the only input parameters which will determine the communication baudrate.
write: the write function takes a command "user-defined", the length of the payload and the effective payload, which has a fixed length of 40 bytes. This function writes this data on UART and returns an error code.
read: It reads the data incoming and insert them in a packet_t struct, defined in.h file. It returs the lenght of the readed buffer if everything works fine, otherwise a negative error.
get_timer: returns the timer's counter
get_APB_clk: return the frequency of APB. Usually APB is used to set periphericals frequency on embedded processors.

Contribution

We are Daniel and Riccardo, both A.I. students at university. We developed this protocol for acquiring data from an ESP32 to do A.I. stuff (check FiremanSam on our Git Repo).

Please consider supporting the project by fixing bugs or adding new feature!

YouTube: https://youtube.com/c/ProjectoOfficial

GitHub: https://github.com/ProjectoOfficial

Code

/* This is a demo of OSCUP protocol, in this example you have to flash this
    firmware on the ESP32 and then run the python code.
    This software is provided AS IS, no Warranties!
    Copyright © 2021 Projecto - Dott. Daniel Rossi, Dott. Riccardo Salami
    License GPL-V3
    @version 1.2.0
    
    @brief this example sketch uses oscup for writing data on UART. It initializes Oscup with a
    fixed ID and Baudrate and initializes the protocol inside void setup function.
    In the void loop it retrieves the value of the APB clock as an uint64_t, then it calls a function
    which converts this value into an array of character and after that it writes this data on UART. 
    Finishing, it calls a free on the buffer.
*/

#include <stdlib.h>
#include "Oscup.h"

uint8_t id = 0x5D;

//constructor takes device's ID and baudrate
Oscup oscup = Oscup(id);

void setup() {
  //it is mandatory to call begin() for starting UART
  oscup.begin(115200);
}

void loop() {
  //this function returns the APB clock frequency (set inside ESP32 libraries)
  uint64_t tim = oscup.get_APB_clk();
  
  //convert uint64_t to byte array
  char *arr2 = uint64_toBytes(tim);
  
  //write the packet, parameters: command(uint8_t), length of the payload(uint8_t), payload(char *)
  uint8_t error = oscup.write((uint8_t)TxCommands::SHARE, sizeof(uint64_t), arr2);
 
  //remember always to free dangling pointers!
  free(arr2);

  
  delay(2000);
}

char *uint64_toBytes(uint64_t number) {
  /*@brief converts a uint64_t into a char * pointer
   * 
   * @param number uint64_t you want to convert
   * 
   * @return the pointer containing the new array of chars
  */
  size_t dim = sizeof(uint64_t);
  char *buff = (char *)calloc(dim, sizeof(char));
  for (int i = 0 ; i < dim; i++) {
    buff[i] = (number >> (8 * i)) & 0xFF;
  }
  return buff;
}

/* This is a demo of OSCUP protocol, in this example you have to flash this
    firmware on the ESP32 and then run the python code.
    This software is provided AS IS, no Warranties!
    Copyright © 2021 Projecto - Dott. Daniel Rossi, Dott. Riccardo Salami
    License GPL-V3
    Version: 1.2.0
*/

#include <stdlib.h>
#include "Oscup.h"

uint8_t id = 0x5D;
packet_t packet;
uint8_t errore = 255;

//constructor takes device's ID and baudrate
Oscup oscup = Oscup(id);

void setup() {
  //it is mandatory to call begin() for starting UART
  oscup.begin(115200);
}

void loop() {
  errore = oscup.read(&packet);

  delay(3000);

}

'''
Oscup: Open Source Custom Uart Protocol
This Software was release under: GPL-3.0 License
Copyright � 2021 Daniel Rossi & Riccardo Salami
Version: ALPHA 1.2.0
'''

from pyOscup import Oscup
from pyOscup import ErrorCodes
from struct import unpack
id = 0x1C
baudrate = 115200
port = "COM3"
oscup = Oscup(id, baudrate, port)

while True:
    error, packet = oscup.read()

    if error:
        if error != ErrorCodes.NO_DATA:
            print("Error: {}".format(error))
    else:
        id, command, length, payload, crc = packet.getParams()
        print("id: {} - command: {} - length: {}".format(hex(id), command, length))
        print("payload: {}".format(payload))
        print("long long value: {}".format(unpack('Q', bytearray(payload[:8]))))
        print("crc: {}".format(crc))
        print("\n\n")

Credits

Daniel Rossi

7 projects • 25 followers

PhD Candidate in ICT @ AImageLab - University of Modena and Reggio Emilia Instagram: @officialprojecto

Custom UART Protocol on ESP32

Things used in this project

Hardware components

Software apps and online services

Story

Description

How it Works

Commands

Public Functions

Contribution

Schematics

ESP32-ESP32 communication

Code

Write

Read

PyRead

OSCUP GitHub

Credits

Daniel Rossi

Comments

Embed the widget on your own site

Custom UART Protocol on ESP32

Custom UART Protocol on ESP32

Things used in this project

Hardware components

Software apps and online services

Story

Description

How it Works

Commands

Public Functions

Contribution

Schematics

ESP32-ESP32 communication

Code

Write

Read

PyRead

OSCUP GitHub

Credits

Daniel Rossi

Comments

Related channels and tags