Skip to main content

Implements a StructuredPacket for pySerial's serial.threaded module

Project description

build-status Latest version released on PyPi


$ pip install serialstruct


When sending a structured binary packet over Serial, the only way (that I’m aware of) to guarantee packet alignment with arbitrary data is to send a header that’s larger than any of the elements and add padding between each element. Here’s an example:

struct Packet {
        int sensor1;
        int sensor2;

If we send this over the wire and start reading at an arbitrary time, it’s impossible to know what byte of the packet we’re reading. To mitigate this we can add a header and some padding.

struct Packet {
        char header[5]; // Any sequence without a '\0'
        int sensor1;
        char pad1;      // '\0'
        int sensor2;
        char pad2;      // '\0'

Now we just need to wait until the header sequence is read and we can consume the rest of the packet without worrying about alignment.

pySerial only implements a FramedPacket which expects a unicode sequence that starts with a ‘(’ (0x28) and ends with a ‘)’ (0x29). This means the bytes 0x28 and 0x29 cannot appear anywhere in the binary data.


Subclass serialstruct.StructuredPacket to specify the data size in the packet and to implement the handle_packet() callback function.

import struct

import serial
import serialstruct
import time

PACKET_STRUCT = struct.Struct("<IxIx")

class MyPacket(serialstruct.StructuredPacket):

    DATA_SIZE = 10 # Excluding header: 4+1+4+1

    def __init__(self):
        super(MyPacket, self).__init__(self.DATA_SIZE)

    def handle_packet(self, packet):

    def send_packet(self, packet):

ser = serial.serial_for_url("loop://", baudrate=115200, timeout=1)
with serial.threaded.ReaderThread(ser, MyPacket) as protocol:
    # unsigned int, pad, unsigned int, pad; with no alignment
    packet = PACKET_STRUCT.pack(1, 2)


(1, 2)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

serialstruct-1.0.24.tar.gz (4.3 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page