ot-tools-io 0.1.2

A library crate for reading/writing binary data files used by the Elektron Octatrack DPS-1.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

# ot-tools-io

rust library crate for reading/writing binary data files used by the [Elektron Octatrack DPS-1](https://www.elektron.se/en/octratrack-mkii-explorer)

[![pipeline status](https://gitlab.com/ot-tools/ot-tools-io/badges/main/pipeline.svg)](https://gitlab.com/ot-tools/ot-tools-io/-/commits/main)
[![coverage report](https://gitlab.com/ot-tools/ot-tools-io/badges/main/coverage.svg)](https://gitlab.com/ot-tools/ot-tools-io/-/commits/main)

# Table of Contents

- [Warnings](./README.md#warnings)
- [License](./README.md#license)
- [About](./README.md#about)
- [Building](./README.md#building)
- [Testing](./README.md#testing)
- [Contributing](./README.md#contributing)
- [Credit](./README.md#credits)

# 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](https://www.gnu.org/licenses/gpl-3.0.en.html).

## About

Library crate for reading/writing Octatrack binary data files.
Most of this is just the [`serde`](https://serde.rs) and 
[`bincode`](https://github.com/bincode-org/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](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
```bash
# dev version
make build
# release version
make build-release
```

# Testing
Running tests
```bash
# 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](./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](https://serde.rs) framework made reverse engineering data files a lot easier, 
  `ot-tools-io` probably wouldn't exist without serde.
- same with [bincode](https://github.com/bincode-org/bincode) for reading the binary data