106 lines
3.9 KiB
Markdown
106 lines
3.9 KiB
Markdown
# Formaty
|
|
A simple configurable binary data parser. Data structures are described using TOML files.
|
|
|
|
## Formats
|
|
All formats in [formats](./formats) are included in the `formaty` binary. See [formats.md](./formats/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](./formats/example.toml)
|
|
|
|
## Example
|
|
```bash
|
|
./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](./LICENSE) |