ot-tools-io

rust library crate for reading/writing binary data files used by the Elektron Octatrack DPS-1

Table of Contents

• Warnings
• License
• About
• Building
• Testing
• Contributing
• Credit

Warnings

• there will be bugs.
• only confirmed work with OS version 1.40B (1.40A and 1.40C should work too).
• should work on windows/macOS, but i mainly develop on linux.
• if you are worried about destroying your Octatrack projects / data files -- take a backup copy of the compact flash card / set / project folder and work on that copy.
• this has mostly been a learning project for me to get to grips with Rust. please do not expect high quality or reliable rust code just yet.
• every function/module/datatype is currently in an 'unstable' state and will possibly (probably) change in the future.
• there will be bugs.

License

This repository, the source code and the libraries generated by the source code are GNU GPL v3.0 licensed.

About

Library crate for reading/writing Octatrack binary data files. Most of this is just the serde and bincode crates with a bunch of function definitions for reading/writing different files or creating new types.

The majority of fields contained within binary data files have been reverse engineered. See the list in ./ot-tools-io/TODO.md for information about missing/unknown data fields.

Current Features (mostly working-ish)

• Read Octatrack binary data files and deserialize into rust types
• Serialize rust types and write into Octatrack binary data files
• Convert Octatrack binary data files into YAML (string or file)
• Convert Octatrack binary data files into JSON (string or file)
• Convert JSON (string or file) into Octatrack binary data files
• Convert YAML (string or file) into Octatrack binary data files

Notes

The JSON / YAML data structures are a bit ... weird. I have done my best to not parse the underlying data into new structures, keeping it so that the library returns data that is as-close-to-the-raw-data-as-possible.

Like, the arrangements data could do with some work to deal with all the {"empty": ""} arranger rows. Header fields probably don't need to be there and can be injected in during deserialization.

ot-tools-io-derive is used to create #[derive(XXXX)] macros for the following

• #[derive(Decodeable)] for the ot_tools_io::Decode trait
• #[derive(Encodeable)] for the ot_tools_io::Encode trait
• #[derive(DefaultsAsArray)] for the ot_tools_io::DefaultsArray trait
• #[derive(DefaultsAsArrayBoxed)] for the ot_tools_io::DefaultsArrayBoxed trait

See the trait descriptions for more information.

Building

# dev version
make build
# release version
make build-release

Testing

Running tests

# basic test running
make test
# test and generate a cobertura coverage report with tarpaulin
make cov

The project is currently hanging around 70%-80%-ish test coverage.

Contributing

See CONTRIBUTING.md.

Help is definitely wanted for

• generating "clean" test data / test cases (one binary data file for each test case)
• improving test coverage
• finishing off the last reverse engineering TODOs

Credits

The following projects were used a starting references for the initial serialization/deserialization efforts of data files (mostly the .ot files). Without them, ot-tools probably wouldn't exist.

• Digichain by brian3kb -- https://github.com/brian3kb/digichain
• OctaChainer by KaiDrange -- https://github.com/KaiDrange/OctaChainer

A special shout out to OctaEdit by Rusty (no longer available http://www.octaedit.com) which showed the community what it was possible to do. Hopefully there are lots of moonbeams and bunny rabbits wherever you are.

Other rust based credits:

• the serde framework made reverse engineering data files a lot easier, ot-tools-io probably wouldn't exist without serde.
• same with bincode for reading the binary data