serialmessage

Crates.ioserialmessage
lib.rsserialmessage
version0.2.0
sourcesrc
created_at2022-10-14 09:26:38.168537
updated_at2024-03-29 10:47:46.780071
descriptionPack serial data into a fast, reliable, and packetized form for communicating with e.g. a Microcontroller.
homepage
repositoryhttps://github.com/LukaOber/serialmessage-rs
max_upload_size
id688074
size231,281
(LukaOber)

documentation

https://docs.rs/serialmessage/

README

Version

serialmessage

serialmessage enables you to pack serial data into a fast, reliable, and packetized form for communicating with e.g. a Microcontroller. It is compatible with the Arduino SerialTransfer and Python pySerialTransfer libraries by PowerBroker2. This crate is designed to be used with any serial crate you desire, and does therefore not implement any serial communication on its own. This crate is optionally fully no_std compatible and can be used on any Microcontroller of your choice.

The message format:

  • uses start and stop bytes
  • uses packet ids
  • uses consistent overhead byte stuffing
  • uses CRC-8 (Polynomial 0x9B with lookup table)
  • allows the use of dynamically sized packets (packets can have payload lengths anywhere from 0 to 254 bytes)
  • can transfer bytes, ints, floats, structs, arrays, vectors

Packet Anatomy:

01111110 00000000 11111111 00000000 00000000 00000000 ... 00000000 10000001
|      | |      | |      | |      | |      | |      | | | |      | |______|__Stop byte (constant)
|      | |      | |      | |      | |      | |      | | | |______|___________8-bit CRC
|      | |      | |      | |      | |      | |      | |_|____________________Rest of payload
|      | |      | |      | |      | |      | |______|________________________2nd payload byte
|      | |      | |      | |      | |______|_________________________________1st payload byte
|      | |      | |      | |______|__________________________________________# of payload bytes
|      | |      | |______|___________________________________________________COBS Overhead byte
|      | |______|____________________________________________________________Packet ID
|______|_____________________________________________________________________Start byte (constant)

Example

Basic Example

use serialmessage::{SerMsg, ParseState};

let send_data_vec: Vec<u8> = vec![1, 2, 3, 4];
let send_msg = SerMsg::create_msg_vec(&send_data_vec, 1).unwrap();
// Send the message bytes with a serial crate of your choice

//Parsing received bytes
let mut ser_msg = SerMsg::new();
let (parse_state, _parsed_bytes) = ser_msg.parse_read_bytes(&send_msg);
match parse_state {
    ParseState::DataReady => {
        let rcvd_data = ser_msg.return_read_data();
        assert_eq!(&send_data_vec, rcvd_data);
    }
    _ => {
        println!("Parsestate: {:?}", parse_state);
    }
}

Using the crate provided examples

If you flash your microcontroller with the code provided in the /examples/arduino_code/ folder you can try the provided examples yourself.

cargo run --example echo your_port

Status of this crate

Current state

This crate is fully functional and tested, I use this crate a lot at work and had no issues so far. If you do encounter an issue or have a question just let me know.

Goals for the future

  • Add no_std microcontroller example
  • Add a timeout parse error

no_std usage

Disable the default features of this crate and you are good to go.

Commit count: 12

cargo fmt