txqr

README

TXQR

TXQR (Transfer via QR) is a protocol and set of tools and libs to transfer data via animated QR codes. It uses fountain codes for error correction.

See related blog posts for more details:

• Animated QR data transfer with Gomobile and Gopherjs
• Fountain codes and animated QR

Demo

Reader iOS app in the demo (uses this lib via Gomobile): https://github.com/divan/txqr-reader

Automated tester app

Also see cmd/txqr-tester app for automated testing of different encoder parameters.

Licence

MIT

Documentation

Overview

Package txqr implements the transmission protocol over QR codes.

Intro

The protocol allows to send a relatively small (fits into the memory fast) data of a known size. Stream data is not supported by design.

QR codes are supposed to be sent and received by means of optical displays and sensors with unknown properties. Sender might be a 85 inch OLED TV with 240Hz rate, while receiver could be an old Android phone with 2MP camera and bound by CPU allowing only 5FPS. Or vice versa. Protocol must adapt to all cases.

The basic idea is to split the data into chunks, suitable for encoding as a single QR frame, add frame header/footer information and run it in the loop.

- splitting into frame is crucial to adapt to desired QR code size/error recovery level

- header and footer contain enough information to uniquely identify frame and be able to restore the whole data even if all frames received out of order.

- loop is needed to make sure slow receiver has enough opportunity to restore from missed frames

All data should be within alphanumeric space. No error correction is implemented, as QR code layer already has one.

Header

    offset/total|<data>

	both offset and total are represents byte position
	and printed in HEX

For, example:

First chunk:

   0/11|hello

Second chunk:

   5/11|world!

Index

• type Decoder
  • func NewDecoder() *Decoder
  • func NewDecoderSize(size, chunkLen int) *Decoder
  • func (d *Decoder) Data() string
  • func (d *Decoder) DataBytes() []byte
  • func (d *Decoder) Decode(chunk string) error
  • func (d *Decoder) IsCompleted() bool
  • func (d *Decoder) Length() int
  • func (d *Decoder) Read() int
  • func (d *Decoder) Reset()
  • func (d *Decoder) Total() int
  • func (d *Decoder) Validate(chunk string) error
• type Encoder
  • func NewEncoder(n int) *Encoder
  • func (e *Encoder) Encode(str string) ([]string, error)
  • func (e *Encoder) SetRedundancyFactor(rf float64)

Types

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder represents protocol decode.

func NewDecoder

func NewDecoder() *Decoder

NewDecoder creates and inits a new decoder.

func NewDecoderSize

func NewDecoderSize(size, chunkLen int) *Decoder

NewDecoderSize creates and inits a new decoder for the known size.

func (*Decoder) Data

func (d *Decoder) Data() string

Data returns decoded data.

func (*Decoder) DataBytes

func (d *Decoder) DataBytes() []byte

DataBytes returns decoded data as a byte slice.

func (*Decoder) Decode

func (d *Decoder) Decode(chunk string) error

Decode takes a single chunk of data and decodes it. Chunk expected to be validated (see Validate) before.

func (*Decoder) IsCompleted

func (d *Decoder) IsCompleted() bool

IsCompleted reports whether the read was completed successfully or not.

func (*Decoder) Length

func (d *Decoder) Length() int

Length returns length of the decoded data. TODO: remove

func (*Decoder) Read

func (d *Decoder) Read() int

Read returns amount of currently read bytes. TODO: remove

func (*Decoder) Reset

func (d *Decoder) Reset()

Reset resets decoder, preparing it for the next run.

func (*Decoder) Total

func (d *Decoder) Total() int

Total returns total amount of data.

func (*Decoder) Validate

func (d *Decoder) Validate(chunk string) error

Validate checks if a given chunk of data is a valid txqr protocol packet.

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder represents protocol encoder.

func NewEncoder

func NewEncoder(n int) *Encoder

NewEncoder creates and inits a new encoder for the given chunk length.

func (*Encoder) Encode

func (e *Encoder) Encode(str string) ([]string, error)

Encode encodes data from reader and splits it into chunks to be futher converted to QR code frames.

func (*Encoder) SetRedundancyFactor

func (e *Encoder) SetRedundancyFactor(rf float64)

SetRedundancyFactor changes the value of redundancy factor.