gpiostream

Documentation

Overview

Package gpiostream defines digital streams.

Warning

This package is still in flux as development is on-going.

Index

• type BitStream
  • func (b *BitStream) Duration() time.Duration
  • func (b *BitStream) Resolution() time.Duration
• type BitStreamLSB
  • func (b *BitStreamLSB) Duration() time.Duration
  • func (b *BitStreamLSB) Resolution() time.Duration
• type BitStreamMSB
  • func (b *BitStreamMSB) Duration() time.Duration
  • func (b *BitStreamMSB) Resolution() time.Duration
• type Bits
• type BitsLSB
• type BitsMSB
• type EdgeStream
  • func (e *EdgeStream) Duration() time.Duration
  • func (e *EdgeStream) Resolution() time.Duration
• type PinIn
• type PinOut
• type Program
  • func (p *Program) Duration() time.Duration
  • func (p *Program) Resolution() time.Duration
• type Stream

Examples

• BitsLSB
• BitsMSB
• PinIn
• PinOut

Types

type BitStream

type BitStream struct {
	Bits Bits
	// The duration each bit represents.
	Res time.Duration
}

BitStream is a stream of Bits to be written or read.

Warning

This struct will be removed in the next major version.

func (*BitStream) Duration

func (b *BitStream) Duration() time.Duration

Duration implement Stream.

func (*BitStream) Resolution

func (b *BitStream) Resolution() time.Duration

Resolution implement Stream.

type BitStreamLSB

type BitStreamLSB struct {
	Bits BitsLSB
	// The duration each bit represents.
	Res time.Duration
}

BitStreamLSB is a stream of BitsLSB to be written or read.

func (*BitStreamLSB) Duration

func (b *BitStreamLSB) Duration() time.Duration

Duration implement Stream.

func (*BitStreamLSB) Resolution

func (b *BitStreamLSB) Resolution() time.Duration

Resolution implement Stream.

type BitStreamMSB

type BitStreamMSB struct {
	Bits BitsMSB
	// The duration each bit represents.
	Res time.Duration
}

BitStreamMSB is a stream of Bits.MSB to be written or read.

func (*BitStreamMSB) Duration

func (b *BitStreamMSB) Duration() time.Duration

Duration implement Stream.

func (*BitStreamMSB) Resolution

func (b *BitStreamMSB) Resolution() time.Duration

Resolution implement Stream.

type Bits

type Bits []byte

Bits is a densely packed LSB-first bitstream.

Warning

This type will be removed in the next major version.

type BitsLSB

type BitsLSB []byte

BitsLSB is a densely packed LSB-first bitstream.

The format is LSB-first, the first bit processed is the least significant one (0x01).

For example, Ethernet uses LSB-first at the byte level and MSB-first at the word level.

The stream is required to be a multiple of 8 samples.

Example

// Format is LSB; least significant bit first.
stream := Bits{0x80, 0x01, 0xAA, 0x55}
for _, l := range stream {
	fmt.Printf("0x%02X: ", l)
	for j := 0; j < 8; j++ {
		mask := byte(1) << uint(j)
		fmt.Printf("%4s,", gpio.Level(l&mask != 0))
		if j != 7 {
			fmt.Printf(" ")
		}
	}
	fmt.Printf("\n")
}

Output:

0x80:  Low,  Low,  Low,  Low,  Low,  Low,  Low, High,
0x01: High,  Low,  Low,  Low,  Low,  Low,  Low,  Low,
0xAA:  Low, High,  Low, High,  Low, High,  Low, High,
0x55: High,  Low, High,  Low, High,  Low, High,  Low,

type BitsMSB

type BitsMSB []byte

BitsMSB is a densely packed MSB-first bitstream.

The format is MSB-first, the first bit processed is the most significant one (0x80).

For example, I²C, I2S PCM and SPI use MSB-first at the word level. This requires to pack words correctly.

The stream is required to be a multiple of 8 samples.

Example

// Format is MSB; most significant bit first.
stream := Bits{0x80, 0x01, 0xAA, 0x55}
for _, l := range stream {
	fmt.Printf("0x%02X: ", l)
	for j := 7; j >= 0; j-- {
		mask := byte(1) << uint(j)
		fmt.Printf("%4s,", gpio.Level(l&mask != 0))
		if j != 0 {
			fmt.Printf(" ")
		}
	}
	fmt.Printf("\n")
}

Output:

0x80: High,  Low,  Low,  Low,  Low,  Low,  Low,  Low,
0x01:  Low,  Low,  Low,  Low,  Low,  Low,  Low, High,
0xAA: High,  Low, High,  Low, High,  Low, High,  Low,
0x55:  Low, High,  Low, High,  Low, High,  Low, High,

type EdgeStream

type EdgeStream struct {
	// Edges is the list of Level change. It is assumed that the signal starts
	// with gpio.High. Use a duration of 0 to start with a Low.
	Edges []time.Duration
	// Res is the minimum resolution at which the edges should be
	// rasterized.
	//
	// The lower the value, the more memory shall be used when rasterized.
	Res time.Duration
}

EdgeStream is a stream of edges to be written.

This struct is more efficient than BitStreamxSB for repetitive pulses, like controlling a servo. A PWM can be created by specifying a slice of twice the same resolution and make it looping via a Program.

func (*EdgeStream) Duration

func (e *EdgeStream) Duration() time.Duration

Duration implement Stream.

func (*EdgeStream) Resolution

func (e *EdgeStream) Resolution() time.Duration

Resolution implement Stream.

type PinIn

type PinIn interface {
	// StreamIn reads for the pin at the specified resolution to fill the
	// provided buffer.
	//
	// May only support a subset of the structs implementing Stream.
	StreamIn(p gpio.Pull, b Stream) error
}

PinIn allows to read a bit stream from a pin.

Caveat

This interface doesn't enable sampling multiple pins in a synchronized way or reading in a continuous uninterrupted way. As such, it should be considered experimental.

Example

// Read one second of sample at 1ms resolution and print the values read.
p := gpioreg.ByName("GPIO3")
r, ok := p.(PinIn)
if !ok {
	log.Fatalf("pin streaming is not supported on pin %s", p)
}
b := BitStream{Res: time.Millisecond, Bits: make(Bits, 1000/8)}
if err := r.StreamIn(gpio.PullNoChange, &b); err != nil {
	log.Fatal(err)
}
for i, l := range b.Bits {
	// Bits format is in MSB; the most significant bit is streamed first.
	for j := 7; j >= 0; j-- {
		mask := byte(1) << uint(j)
		fmt.Printf("%4s, ", gpio.Level(l&mask != 0))
	}
	if i&1 == 1 {
		fmt.Printf("\n")
	}
}

type PinOut

type PinOut interface {
	StreamOut(s Stream) error
}

PinOut allows to stream to a pin.

The Stream may be a Program, a BitStream or an EdgeStream. If it is a Program that is an infinite loop, a separate goroutine can be used to cancel the program. In this case StreamOut() returns without an error.

Caveat

This interface doesn't enable streaming to multiple pins in a synchronized way or reading in a continuous uninterrupted way. As such, it should be considered experimental.

Example

// Generates a 25% duty cycle PWM at 1kHz for 5 seconds with a precision of
// 1µs.
p := gpioreg.ByName("GPIO3")
r, ok := p.(PinOut)
if !ok {
	log.Fatalf("pin streaming is not supported on pin %s", p)
}
b := Program{
	Parts: []Stream{
		&EdgeStream{
			Res:   time.Microsecond,
			Edges: []time.Duration{250 * time.Microsecond, 750 * time.Microsecond},
		},
	},
	Loops: 5000,
}
if err := r.StreamOut(&b); err != nil {
	log.Fatal(err)
}

type Program

type Program struct {
	Parts []Stream // Each part must be a BitStream, EdgeStream or Program
	Loops int      // Set to -1 to create an infinite loop
}

Program is a loop of streams.

This is itself a stream, it can be used to reduce memory usage when repeated patterns are used.

func (*Program) Duration

func (p *Program) Duration() time.Duration

Duration implement Stream.

func (*Program) Resolution

func (p *Program) Resolution() time.Duration

Resolution implement Stream.

type Stream

type Stream interface {
	// Resolution is the minimum resolution of the binary stream at which it is
	// usable.
	Resolution() time.Duration
	// Duration of the binary stream. For infinitely looping streams, it is the
	// duration of the non-looping part.
	Duration() time.Duration
}

Stream is the interface to define a generic stream.