search

lexus2k / tinyproto

Tiny Software Protocol for communication over UART, SPI, etc
GNU General Public License v3.0
240 stars 51 forks source link
arduino atmega avr communication esp32 hdlc hdlc-like microcontroller protocol protocol-library rfc1662 serial serialport spi spi-protocol win32 windows-desktop

readme

Tiny Protocol

Github actions Coverage Status Documentation License License

Introduction

Tiny Protocol is LAYER 2 protocol. It is intended to be used for the systems with low resources. It is also can be compiled for desktop Linux system, and it can be built for Windows. Using this library you can easy implement data transfer between 2 microcontrollers or between microcontroller and pc via UART, SPI, I2C or any other communication channels. You don't need to think about data synchronization between points. The library use no dynamic allocation of memory.

TinyProto is based on RFC 1662. Tiny Protocol supports 2 HDLC modes: ABM (for peer to peer connections) and NRM (for multi-drop connections).

Tiny Protocol is NOT an application layer protocol, although, for example, it can be used with Protocol Buffers. The protocol supports ABM and NRM modes.

Key Features

Main features:

Supported platforms

Platform Examples
ESP32 IDF
Cortex M0 Zero
Linux Linux
Windows Win32
Other Any platform with implemented HAL

What if my platform is not yet supported?

That's not a problem. Just implement abstraction layer for your platform (timing and mutex functions). Please go through the steps below:

Refer to tiny_hal_init() function. To understand HAL implementation refer to Linux and ESP32 examples in HAL abstraction layer. You may use template code platform_hal.c

Easy to use

Cpp

Usage of light Tiny Protocol in C++ can look like this:

#include "tinyproto.h"

tinyproto::Light  proto;
tinyproto::Packet<256> packet;

void setup() {
    ...
    proto.beginToSerial();
}

void loop() {
    if (Serial.available()) {
        int len = proto.read( packet );
        if (len > 0) {
            /* Send message back */
            proto.write( packet );
        }
    }
}

Example of using full duplex Tiny Protocol in C++ is a little bit bigger, but it is still simple:

#include "tinyproto.h"

tinyproto::Fd<FD_MIN_BUF_SIZE(64,4)>  proto;

void onReceive(void *udata, tinyproto::IPacket &pkt) {
    // Process message here, you can do with the message, what you need
    // Let's send it back to the sender ;)
    if ( proto.write(pkt) == TINY_ERR_TIMEOUT ) {
        // Do what you need to do if looping back failed on timeout.
        // But never use blocking operations inside callback
    }
}

void setup() {
    ...
    // Here we say FD protocol object, which callback to call once new msg is received
    proto.setReceiveCallback( onReceive );
    proto.begin();
}

void loop() {
    if (Serial.available()) {
        uint8_t byte = Serial.read();
        proto.run_rx( &byte, 1 ); // run FD protocol parser to process data received from the channel
    }
    uint8_t byte;
    if ( proto.run_tx( &byte, 1 ) == 1 ) // FD protocol fills buffer with data, we need to send to the channel
    {
        while ( Serial.write( byte ) == 0 ); // Just send the data
    }
}

Python

import tinyproto

p = tinyproto.Hdlc()
def on_read(a):
    print("Received bytes: " + ','.join( [ "{:#x}".format(x) for x in a ] ) )

# setup protocol
p.on_read = on_read
p.begin()

# provide rx bytes to the protocol, obtained from hardware rx channel
p.rx( bytearray([ 0x7E, 0xFF, 0x3F, 0xF3, 0x39, 0x7E  ]) )

How to build

Linux

make
# === OR ===
mkdir build
cd build
cmake -DEXAMPLES=ON ..
make

Windows

mkdir build
cd build
cmake -G "Visual Studio 16 2019" -DEXAMPLES=ON ..

ESP32

Just place the library to your project components folder.

Setting up

Using tiny_loopback tool

For more information about this library, please, visit https://github.com/lexus2k/tinyproto. Doxygen documentation can be found at Codedocs xyz site. If you found any problem or have any idea, please, report to Issues section. If you find the library useful and want to support future development, you may contact me.

Paypal Bitcoin Etherium
Not available
BTC
3CtUY6Ag2zsvm1JyqeeKeK8kjdG7Tnjr5W
ETH
0x20608A71470Bc84a3232621819f578Fb9C02A460

License

The project is released under dual license: GPLv3, or Commercial license.

Copyright 2016-2024 (C) Alexey Dynda

This file is part of Tiny Protocol Library.

GNU General Public License Usage

Protocol Library is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Protocol Library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with Protocol Library. If not, see http://www.gnu.org/licenses/.

Commercial License Usage

Licensees holding valid commercial Tiny Protocol licenses may use this file in accordance with the commercial license agreement provided in accordance with the terms contained in a written agreement between you and Alexey Dynda. For further information contact via email on github account.