Make arbitrary byte streams human readable!
Go to file
Joey Hines 38ed49fbe3
ci/woodpecker/tag/woodpecker Pipeline was successful Details
Added deframer support
2024-08-17 15:58:25 -06:00
formats Added deframer support 2024-08-17 15:58:25 -06:00
src Added deframer support 2024-08-17 15:58:25 -06:00
.gitignore Initial Commit 2021-09-11 12:21:34 -06:00
.woodpecker.yml Bump rust version to help woodpecker out 2024-04-28 15:51:30 -06:00
Cargo.lock Added deframer support 2024-08-17 15:58:25 -06:00
Cargo.toml Added deframer support 2024-08-17 15:58:25 -06:00
LICENSE Added README.md LICENSE.md 2021-10-09 14:09:21 -06:00
README.md Added deframer support 2024-08-17 15:58:25 -06:00

README.md

Formaty

A simple configurable binary data parser. Data structures are described using TOML files.

Formats

All formats in formats are included in the formaty binary. See formats.md for more info.

Configuration

Format

A format is a collection of fields that describe the structure of data, so it can be parsed

Members:

  • name - name of the format, used as the argument when selecting the format to parse the data as
  • bit_flip - should individual bytes have their bits flipped within, individual fields can override this
  • deframer - optional list of deframers to use before trying to parse the data
  • fields - 1 or more fields to describe the structure of the data

Field

A field is a collection of bits that make up some sort of data. Formaty supports Int/Uint of arbitrary size, Float, Double, Strings and Bytes. This data does not need to be byte aligned.

Members:

  • name - the name of the field, used while displaying data
  • field_type - the type of the field and associated data
  • print_type - how to print the data, if not provided it uses the default print for a type
  • bit_flip - overrides the global bit flip field, defaults to false if not provided

Field Types

  • UInt/Int: standard integer types. Unsigned or signed respectively. Can be 1 or more bits.
    • bit_width: number of bits composing the integer
    • endianess: byte ordering of the field
  • Float/Double: Standard float point types of 32-bit or 64-bit width
    • endianess: byte ordering of the field
  • String: Collection of bytes ended by a null character '\0'
    • max_len: max length of the data
    • endianess: byte ordering of the field
  • Bytes: Collection of bytes with no termination
    • max_len: max number of bytes
    • endianess: byte ordering of the field
  • Format: Allows formats to include other formats
    • format_name: Format definition to use

Print Types

  • Base: print out the field as of a number of base N
  • ByteArray: display the field as an array of bytes
  • String: view fields as a string field
  • Default: use the default printer for the source type

Deframer

A deframer configures how the data should be unpacked before being parsed. A deframer is made up of one or more DeframeOperations. Deframers can be added to Format configs or be applied by passing in the --deframer option.

Deframe Operation

  • StartSeq - a start sequence of bytes to check for and remove before parsing
  • StopSeq - a stop sequence of bytes to check for and remove before parsing
  • Replace - a simple find and replace with Regex support. All matches of find are replaced with replace

Example Config

Example

Example

./formaty ccsds "[0xe0, 0xa1, 0xc0, 0x00, 0x00, 0x05, 0x01, 0x02, 0x03, 0x04, 0x05]"

Output:

Version Number: 0
Packet Type: 1
Secondary Header Flag: 0
APID: 0x200
Sequence Flags: 3
Packet Sequence Count: 0
Data Length: 5
Data: [1, 2, 3, 4, 5]

Help

Formaty 0.3.0
Arbitrary Binary Data Formatting

USAGE:
    formaty [FLAGS] [OPTIONS] <format> [--] [data]...

FLAGS:
    -h, --help       Prints help information
    -s, --stdin      Input data from stdin
    -V, --version    Prints version information

OPTIONS:
    -b, --base <base>                      Base of the input values
    -c, --config <config>                  Path to the format config [env: FORMATY_CONFIG=]
    -d, --deframer <deframer>...           Additional deframers to apply to the data before trying to parse it
    -g, --global_config <global-config>    Path to the global config directory [env: FORMATY_GLOBAL_CONFIG=]
    -f, --file <input-file>                Input data from file
    -i, --input_type <input-type>          Input data type [default: array]

ARGS:
    <format>     Format to parse data as
    <data>...    Raw data

License

License