This is a Python based implementation for parsing binary files from the Aidee EmBody device.
- Converts binary embody files to HDF, CSV, etc
- Integrates with the EmBody Protocol Codec project
- CLI (command line interface)
- Can be used as package in other projects
- Type safe code using mypy for type checking
- Python 3.8-3.10
You can install Embody File via pip:
$ pip install embody-file
To use the command line, first install this library either globally or using venv:
$ pip install embody-file
When this library has been installed, a new command is available, embody-file
which can be used according to the examples below:
To get an updated overview of all command line options:
embody-file --help
embody-file --version
To convert to a HDF 5 (hierarcical data format) format, run the following:
embody-file testfiles/v5_0_0_test_file.log --output-format HDF
The file will be named the same as the input file, with the .hdf
extension at the end of the file name.
To convert to CSV format, run the following:
embody-file testfiles/v5_0_0_test_file.log --output-format CSV
The file will be named the same as the input file, with the .csv
extension at the end of the file name.
To print stats without conversion:
embody-file testfiles/v5_0_0_test_file.log --print-stats
The parser is lenient by default, accepting errors in the input file. If you want to the parsing to fail on any errors, use the --strict
flag:
embody-file testfiles/v5_0_0_test_file.log --strict
To show an ECG/PPG plot graph:
embody-file testfiles/v5_0_0_test_file.log --plot
To get the best overview, start by running the parser in strict mode and with debug logging, so it stops at the first error:
embody-file troublesomefile.log --strict --log-level DEBUG
This provides positional information per message so it's easier to continue searching for errors.
If this doesn't give us enough information, look at the protocol documentation and start looking and the problematic areas in the input file.
There are several command line tools you can use. On MAC and Linux, one good example is to use the hexdump
tool:
hexdump -C -n 70 -s 0 troublesomefile.log
Here, -n 70
is the amount of bytes to print in hex format, and -s 0
tells hexdump to start at position 0 in the file. Adjust these parameters according to your needs.
Make a note from the parser's error output of what position the first error started from, and based on that:
- Look at the preceding bytes to see whether there were any errors in the previous protocol message
- Look at the bytes from the reported (error) position to see if there are just a few bytes before a new, plausible protocol message starts
Contributions are very welcome. To learn more, see the Contributor Guide.
If you encounter any problems, please file an issue along with a detailed description.