goasterix

README

GoAsterix

This library provides an ASTERIX Frame(binary data) decoding/parsing(json,xml) capabilities for Go.

ASTERIX

ASTERIX (All Purpose Structured EUROCONTROL Surveillance Information Exchange) is an application/presentation protocol responsible for data definition and data assembly developed to support the transmission and exchange of surveillance related data. Its purpose is to allow a meaningful transfer of information between two application entities using a mutually agreed representation of the data to be exchanged.

More about ASTERIX: Eurocontrol asterix

Documentation

• API Reference
• Hex to String example
• Decode binary file example
• Parsing Json example

Installation

go get github.com/mokhtarimokhtar/goasterix

Documentation

Overview

Package goasterix parses ASTERIX binary data Format.

Package goasterix provides an ASTERIX (All Purpose Structured EUROCONTROL Surveillance Information Exchange) packet decoding and marshalling JSON/XML for the Go language. datablock.go and record.go contain the logic built into goasterix for decoding packet datagram.

goasterix contains some sub-packages including:

• uap: This contains all definition ASTERIX Profile (User Application Profile).
• transform: This contains of the logic marshalling in JSON or XML format.
• commbds: It is for decoding Comm-B Data Selector of transponder (ICAO Doc 9871:Technical Provisions for Mode S Services and Extended Squitter)

Data Block corresponds at general message structure. It contains:

• a one-octet field Data Category (CAT) indicating to which Category the data transmitted belongs;
• two-octet field Length Indicator (LEN) indicating the total length (in octets) of the Data Block, including the CAT and LEN fields;
• one or more Record(s) containing data of the same Category.

Data Record contains:

• a Field Specification (FSPEC) field of variable length, considered as a table of contents, in the form of a bit sequence, where every individual bit signals the presence (bit set to one) or absence (bit set to zero) of a well-defined Data Field assigned to it;
• a variable number of Data Fields. Each Data Field is associated with one and only one Data Item, as defined by the UAP.

Describe an UAP definition: todo Basic Usage: todo

Index

• Variables
• func FspecIndex(fspec []byte) []uint8
• func FspecReader(reader io.Reader) ([]byte, error)
• func TwoComplement16(sizeBits uint8, data uint16) (v int16)
• func TwoComplement32(sizeBits uint8, data uint32) (v int32)
• type Compound
  • func CompoundDataFieldReader(rb *bytes.Reader, cp []uap.DataField) (Compound, error)
  • func (c *Compound) Payload() []byte
  • func (c Compound) String() string
• type DataBlock
  • func NewDataBlock() *DataBlock
  • func (db *DataBlock) Decode(data []byte) (int, error)
  • func (db DataBlock) Payload() [][]byte
  • func (db DataBlock) String() [][]string
• type Explicit
  • func ExplicitDataFieldReader(rb *bytes.Reader) (Explicit, error)
  • func (e *Explicit) Payload() []byte
  • func (e *Explicit) String() string
• type Extended
  • func ExtendedDataFieldReader(rb *bytes.Reader, primarySize uint8, secondarySize uint8) (Extended, error)
  • func (e *Extended) Payload() []byte
  • func (e *Extended) String() string
• type Fixed
  • func FixedDataFieldReader(rb *bytes.Reader, size uint8) (Fixed, error)
  • func (f *Fixed) Payload() []byte
  • func (f *Fixed) String() string
• type Item
  • func NewItem(field uap.DataField) *Item
  • func (i *Item) Payload() []byte
  • func (i *Item) String() string
• type MetaItem
• type RandomField
• type RandomFieldSequencing
  • func RFSDataFieldReader(rb *bytes.Reader, items []uap.DataField) (RandomFieldSequencing, error)
• type Record
  • func NewRecord() *Record
  • func (rec *Record) Decode(data []byte, stdUAP uap.StandardUAP) (unRead int, err error)
  • func (rec Record) Payload() []byte
  • func (rec Record) String() []string
• type Repetitive
  • func RepetitiveDataFieldReader(rb *bytes.Reader, SubItemSize uint8) (Repetitive, error)
  • func (r *Repetitive) Payload() []byte
  • func (r *Repetitive) String() string
• type SPandREField
  • func SPAndREDataFieldReader(rb *bytes.Reader) (SPandREField, error)
• type WrapperDataBlock
  • func NewWrapperDataBlock() (*WrapperDataBlock, error)
  • func (w *WrapperDataBlock) Decode(data []byte) (unRead int, err error)

Variables

var (
	// ErrUndersized reports that the data byte source is too small.
	ErrUndersized = errors.New("[ASTERIX] undersized packet")

	// ErrCategoryUnknown reports which Category Unknown or not processed.
	ErrCategoryUnknown = errors.New("[ASTERIX] category unknown or not processed")
)

var (
	// ErrDataFieldUnknown reports which ErrDatafield Unknown.
	ErrDataFieldUnknown = errors.New("type of datafield not found")
)

Functions

func FspecIndex

func FspecIndex(fspec []byte) []uint8

FspecIndex returns an array of uint8 corresponding to number FRN(Field Reference Number of Items). In other words, it transposes a fspec bits to an array FRNs. e.g. fspec = 1010 1010 => frnIndex = []uint8{1, 3, 5, 7}

func FspecReader

func FspecReader(reader io.Reader) ([]byte, error)

FspecReader returns a slice of FSPEC data record asterix.

func TwoComplement16

func TwoComplement16(sizeBits uint8, data uint16) (v int16)

TwoComplement16 returns an int16 (signed). sizeBits is the number of bit complement.

func TwoComplement32

func TwoComplement32(sizeBits uint8, data uint32) (v int32)

TwoComplement32 returns an int32 (signed). sizeBits is the number of bit complement.

Types

type Compound

type Compound struct {
	Primary   []byte
	Secondary []Item
}

func CompoundDataFieldReader

func CompoundDataFieldReader(rb *bytes.Reader, cp []uap.DataField) (Compound, error)

CompoundDataFieldReader Compound Data Fields, being of a variable length, shall comprise a primary subfield, followed by data subfields. The primary subfield determines the presence or absence of the subsequent data subfields. It comprises a first part of one octet extendable using the Field Extension (FX) mechanism. The definition, structure and format of the data subfields are part of the description of the relevant Compound Data Item. Data subfields shall be either fixed length, extended length, explicit length or repetitive, but not compound.

func (*Compound) Payload

func (c *Compound) Payload() []byte

func (Compound) String

func (c Compound) String() string

type DataBlock

type DataBlock struct {
	Category uint8
	Len      uint16
	Records  []*Record
}

DataBlock a DataBlock corresponds to one (only) category and contains one or more Records. DataBlock = CAT + LEN + [FSPEC + items...] + [...] + ...

func NewDataBlock

func NewDataBlock() *DataBlock

func (*DataBlock) Decode

func (db *DataBlock) Decode(data []byte) (int, error)

Decode extracts an asterix data block: CAT + LEN + N * RECORD(S). An asterix data block can contain a or more records. It returns the number of bytes unRead and fills the DataBlock Struct(Category, Len, Records array) in byte.

func (DataBlock) Payload

func (db DataBlock) Payload() [][]byte

func (DataBlock) String

func (db DataBlock) String() [][]string

type Explicit

type Explicit struct {
	Len  uint8
	Data []byte
}

func ExplicitDataFieldReader

func ExplicitDataFieldReader(rb *bytes.Reader) (Explicit, error)

ExplicitDataFieldReader extracts a number of bytes define by the first byte. Explicit length Data Fields shall start with a one-octet length indicator giving the total field length in octets including the length indicator itself.

func (*Explicit) Payload

func (e *Explicit) Payload() []byte

func (*Explicit) String

func (e *Explicit) String() string

type Extended

type Extended struct {
	Primary   []byte
	Secondary []byte
}

func ExtendedDataFieldReader

func ExtendedDataFieldReader(rb *bytes.Reader, primarySize uint8, secondarySize uint8) (Extended, error)

ExtendedDataFieldReader extracts data item type Extended (FX: last bit = 1). primarySize parameter defines the Primary Subitem of extended field. secondarySize parameter defines the Secondary Subitem of extended field. Extended length Data Fields, being of a variable length, shall contain a primary part of predetermined length, immediately followed by a number of secondary parts, each of predetermined length. The presence of the next following secondary part shall be indicated by the setting to one of the Least Significant Bit (LSB) of the last octet of the preceding part (either the primary part or a secondary part). This bit which is reserved for that purpose is called the Field Extension Indicator (FX).

func (*Extended) Payload

func (e *Extended) Payload() []byte

func (*Extended) String

func (e *Extended) String() string

type Fixed

type Fixed struct {
	Data []byte
}

func FixedDataFieldReader

func FixedDataFieldReader(rb *bytes.Reader, size uint8) (Fixed, error)

FixedDataFieldReader extracts a number(nb) of bytes(size) and returns a slice of bytes(data of item). Fixed length Data Fields shall comprise a fixed number of octets.

func (*Fixed) Payload

func (f *Fixed) Payload() []byte

func (*Fixed) String

func (f *Fixed) String() string

type Item

type Item struct {
	Meta       MetaItem
	Fixed      *Fixed
	Extended   *Extended
	Explicit   *Explicit
	Repetitive *Repetitive
	Compound   *Compound
	RFS        *RandomFieldSequencing
	SP         *SPandREField
	RE         *SPandREField
}

func NewItem

func NewItem(field uap.DataField) *Item

func (*Item) Payload

func (i *Item) Payload() []byte

func (*Item) String

func (i *Item) String() string

type MetaItem

type MetaItem struct {
	FRN         uint8
	DataItem    string
	Description string
	Type        uap.TypeField
}

type RandomField

type RandomField struct {
	FRN   uint8
	Field Item
}

type RandomFieldSequencing

type RandomFieldSequencing struct {
	N        uint8
	Sequence []RandomField
}

func RFSDataFieldReader

func RFSDataFieldReader(rb *bytes.Reader, items []uap.DataField) (RandomFieldSequencing, error)

RFSDataFieldReader The RFS organised field is a collection of Data Fields which in contrast to the OFS organisation, can occur in any order. The RFS organised field shall be structured as follows: - the first octet provides the number, N, of Data Fields following; - N fields in any arbitrary order each consisting of a one-octet FRN immediately followed by the contents of the Data Item associated with the preceding FRN.

type Record

type Record struct {
	Cat   uint8
	Fspec []byte
	Items []Item
}

func NewRecord

func NewRecord() *Record

func (*Record) Decode

func (rec *Record) Decode(data []byte, stdUAP uap.StandardUAP) (unRead int, err error)

Decode extracts a Record of asterix data block (only one record). An asterix data block can contain a or more records. It returns the number of bytes unread and fills the Record Struct(Fspec, Items array) in byte.

func (Record) Payload

func (rec Record) Payload() []byte

Payload returns a slice of byte for one asterix record.

func (Record) String

func (rec Record) String() []string

String returns a string(hex) representation of one asterix record (only existing items).

type Repetitive

type Repetitive struct {
	Rep  uint8
	Data []byte
}

func RepetitiveDataFieldReader

func RepetitiveDataFieldReader(rb *bytes.Reader, SubItemSize uint8) (Repetitive, error)

RepetitiveDataFieldReader extracts data item type Repetitive(1+rep*N byte). The first byte is REP(factor), nb is the size of bytes to repetition. Repetitive Data Fields, being of a variable length, shall comprise a one-octet Field Repetition Indicator (REP) signalling the presence of N consecutive sub-fields each of the same pre-determined length.

func (*Repetitive) Payload

func (r *Repetitive) Payload() []byte

func (*Repetitive) String

func (r *Repetitive) String() string

type SPandREField

type SPandREField struct {
	Len  uint8
	Data []byte
}

SPandREField The Reserved Expansion Field is used only until and including Edition 2.1 of Part 1 of the ASTERIX documentation. The Reserved Expansion Data field is intended to provide a mechanism to introduce intermediate changes to a given category, as explained in 7.2.3. In a way similar to the Special Purpose mechanism,

func SPAndREDataFieldReader

func SPAndREDataFieldReader(rb *bytes.Reader) (SPandREField, error)

SPAndREDataFieldReader extracts returns a slice ref. EUROCONTROL-SPEC-0149 2.4 4.3.5 Non-Standard Data Fields: Reserved Expansion Data Field Special Purpose field

type WrapperDataBlock

type WrapperDataBlock struct {
	DataBlocks []*DataBlock
}

WrapperDataBlock a Wrapper DataBlock correspond to one or more category and contains one or more Records. DataBlock = CAT + LEN + [FSPEC + items...] + [...] + ... WrapperDataBlock = [CAT + LEN + RECORD + ...] + [ DATABLOCK ] + [...]

func NewWrapperDataBlock

func NewWrapperDataBlock() (*WrapperDataBlock, error)

func (*WrapperDataBlock) Decode

func (w *WrapperDataBlock) Decode(data []byte) (unRead int, err error)