ledserial

README

Package ledserial implements a program that reads LED colors from the UART serial input and displays them on the LED strip.

Protocol

The protocol defines a simple byte protocol for sending various packet types over the wire.

Scalar Types

The following scalar types are defined:

- uint8:   1 byte unsigned integer
- uint16:  2 byte unsigned integer, little endian
- uint32:  4 byte unsigned integer, little endian
- int8:    1 byte signed integer
- int16:   2 byte signed integer, little endian
- int32:   4 byte signed integer, little endian
- float32: 4 byte IEEE 754 floating point number, little endian
- string:  uint16 length followed by a UTF-8 encoded string of the given
           length
- bytes:   uint16 length followed by the given number of bytes

Incoming Packet

Each packet starts with a single byte that defines the packet type. The following packet types are defined:

0x00: Initialize packet. This must be sent before any other packet.
0x01: Clear all LEDs.
0x02: Set all LEDs to the given colors.

All packets must be suffixed with a CRC32 checksum with the IEEE polynomial. The checksum is calculated over the entire packet, including the packet type. The checksum is sent as a uint32.

The packet structure can be understood as follows:

0x00: Packet type (uint8)
0x01: Packet data of known length depending on the packet type
0xNN: CRC32 checksum (uint32)

The packet data depends on the packet type.

Initialize Packet

The initialize packet is sent as a single byte with value 0x00. It resets the LED strip to its initial state. The packet requires the following data:

0x00: 0x01 value (uint8)
0x01: Number of LEDs (uint16)

Clear Packet

The clear packet is sent as a single byte with value 0x01. It clears all LEDs to black. The packet requires no additional data.

Set Packet

The set packet is sent as a single byte with value 0x02. It sets all LEDs to the given colors. The packet requires the following data:

0x00: 0x02 value (uint8)
0x01: Red value of the first LED (uint8)
0x02: Green value of the first LED (uint8)
0x03: Blue value of the first LED (uint8)
0x04: Red value of the second LED (uint8)
0x05: Green value of the second LED (uint8)
0x06: Blue value of the second LED (uint8)
...

The total number of LEDs must be equal to the number of LEDs specified in the initialize packet. The total length of the packet would be 3*numLEDs + 1.

To better visualize the packet structure, here is a diagram of the packet structure:

+--------+--------+--------+--------+--------+--------+--------+--------+
+ Type   | Data                                                         |
+--------+--------+--------+--------+--------+--------+--------+--------+
| 0x02   | LED 0                    | LED 1                    | ...	|
+        +                          +                          +        +
|        | Red    | Green  | Blue   | Red    | Green  | Blue   | ...	|
+--------+--------+--------+--------+--------+--------+--------+--------+

Outgoing Packet

Each packet starts with a single byte that defines the packet type. The following packet types are defined:

0x00: Error packet. This is sent when an error occurs.
0x01: Panic packet. This is sent when the program cannot recover.
0x03: Log packet. This is sent when the program wants to log a message.
0x04: Acknowledgement packet. This is sent when a packet is received.

The packet structure can be similarly understood as the incoming packet.

Error Packet

The error packet is sent as a single byte with value 0x00. It indicates that an error occurred. The packet requires the following data:

0x00: 0x00 value (uint8)
0x01: Error message (string)

Panic Packet

The panic packet is sent as a single byte with value 0x01. It indicates that the program cannot recover. The packet requires the following data:

0x00: 0x01 value (uint8)

Log Packet

The log packet is sent as a single byte with value 0x03. It indicates that the program wants to log a message. The packet requires the following data:

0x00: 0x03 value (uint8)
0x01: Log message (string)

Documentation

Overview

Package ledserial implements the LED serial protocol.

Index

• Variables
• func WriteIncomingPacket(w io.Writer, p IncomingPacket) error
• func WriteOutgoingPacket(w io.Writer, p OutgoingPacket) error
• type AckPacket
  • func (p AckPacket) Type() OutgoingPacketType
• type ClearPacket
  • func (p ClearPacket) Type() IncomingPacketType
• type ErrorPacket
  • func (p ErrorPacket) Type() OutgoingPacketType
• type IncomingPacket
  • func ReadIncomingPacket(r io.Reader, context ReadContext) (IncomingPacket, error)
• type IncomingPacketType
  • func (t IncomingPacketType) String() string
• type InitializePacket
  • func (p InitializePacket) Type() IncomingPacketType
• type LogPacket
  • func (p LogPacket) Type() OutgoingPacketType
• type OutgoingPacket
  • func ReadOutgoingPacket(r io.Reader, context ReadContext) (OutgoingPacket, error)
• type OutgoingPacketType
  • func (t OutgoingPacketType) String() string
• type PanicPacket
  • func (p PanicPacket) Type() OutgoingPacketType
• type ReadContext
• type Reader
• type SetPacket
  • func (p SetPacket) Type() IncomingPacketType

Variables

var Endianness = binary.LittleEndian

Endianness defines the endianness of the protocol.

Functions

func WriteIncomingPacket

func WriteIncomingPacket(w io.Writer, p IncomingPacket) error

WriteIncomingPacket writes an incoming packet to the given writer.

func WriteOutgoingPacket

func WriteOutgoingPacket(w io.Writer, p OutgoingPacket) error

WriteOutgoingPacket writes an outgoing packet to the given writer.

Types

type AckPacket

type AckPacket struct {
	IncomingPacketType IncomingPacketType
}

AckPacket is a packet that is sent by the controller to acknowledge a packet.

func (AckPacket) Type

func (p AckPacket) Type() OutgoingPacketType

type ClearPacket

type ClearPacket struct{}

ClearPacket is a packet that clears the LED strip.

func (ClearPacket) Type

func (p ClearPacket) Type() IncomingPacketType

type ErrorPacket

type ErrorPacket struct {
	Message string
}

ErrorPacket is a packet that indicates an error occurred.

func (ErrorPacket) Type

func (p ErrorPacket) Type() OutgoingPacketType

type IncomingPacket

type IncomingPacket interface {
	// Type returns the type of packet.
	Type() IncomingPacketType
}

IncomingPacket is a packet sent over the wire.

func ReadIncomingPacket

func ReadIncomingPacket(r io.Reader, context ReadContext) (IncomingPacket, error)

ReadIncomingPacket reads an incoming packet from the given reader.

type IncomingPacketType

type IncomingPacketType uint8

IncomingPacketType is a type of packet.

const (
	TypeInitializePacket IncomingPacketType = iota
	TypeClearPacket
	TypeSetPacket
)

func (IncomingPacketType) String

func (t IncomingPacketType) String() string

String returns a string representation of the packet type.

type InitializePacket

type InitializePacket struct {
	NumLEDs uint16
}

InitializePacket is a packet that initializes the LED strip.

func (InitializePacket) Type

func (p InitializePacket) Type() IncomingPacketType

type LogPacket

type LogPacket struct {
	Message string
}

LogPacket is a packet that contains a log message.

func (LogPacket) Type

func (p LogPacket) Type() OutgoingPacketType

type OutgoingPacket

type OutgoingPacket interface {
	// Type returns the type of packet.
	Type() OutgoingPacketType
}

OutgoingPacket is a packet sent over the wire.

func ReadOutgoingPacket

func ReadOutgoingPacket(r io.Reader, context ReadContext) (OutgoingPacket, error)

ReadOutgoingPacket reads an outgoing packet from the given reader.

type OutgoingPacketType

type OutgoingPacketType uint8

OutgoingPacketType is a type of packet.

const (
	TypeErrorPacket OutgoingPacketType = iota
	TypeLogPacket
	TypeAckPacket
)

const TypePanicPacket OutgoingPacketType = 'p'

TypePanicPacket is a special constant. It is the first letter of the word "panic" in order to parse the string itself as a packet type.

func (OutgoingPacketType) String

func (t OutgoingPacketType) String() string

String returns a string representation of the packet type.

type PanicPacket

type PanicPacket struct {
	Message string
}

PanicPacket is a packet that indicates the program cannot recover.

func (PanicPacket) Type

func (p PanicPacket) Type() OutgoingPacketType

type ReadContext

type ReadContext struct {
	// LEDBuffer is the buffer that contains the current state of the LED strip.
	// This buffer will be used for reading SetPacket.
	// Its length must be NumLEDs * 3.
	LEDBuffer []uint8
}

ReadContext is the state of the LED strip. Data in this structure are required for the device to read incoming packets.

type Reader

type Reader interface {
	io.ByteReader
	io.Reader
}

Reader is a reader that reads packets.

type SetPacket

type SetPacket struct {
	Pix []uint8
}

SetPacket is a packet that sets the LED strip to the given colors.

func (SetPacket) Type

func (p SetPacket) Type() IncomingPacketType