Skip to main content
Warning: You are using the test version of PyPI. This is a pre-production deployment of Warehouse. Changes made here affect the production instance of TestPyPI (
Help us improve Python packaging - Donate today!

Implements a StructuredPacket for pySerial's serial.threaded module

Project Description


$ 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)
Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

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

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
serialstruct-1.1.0.tar.gz (4.3 kB) Copy SHA256 Checksum SHA256 Source Apr 28, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting