ebds: EBDS protocol messages and related types

Messages and related types for the EBDS serial communication protocol.

.github/workflows/ebds.yml

@@ -0,0 +1,102 @@
+name: ebds
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  rustfmt-clippy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install stable
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          components: rustfmt, clippy
+
+      - name: Run rustfmt
+        uses: actions-rs/cargo@v1
+        with:
+          command: fmt
+          args: -- --check
+
+      - name: Run clippy
+        uses: actions-rs/cargo@v1
+        with:
+          command: clippy
+          args: --tests
+
+  test:
+    runs-on: ${{matrix.os}}
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        target:
+          - debian: null
+            cross: null
+            rust: null
+        llvm_version: ["5.0", "9.0"]
+        main_tests: [1]
+        release_build: [0, 1]
+        no_default_features: [0, 1]
+        # FIXME: There are no pre-built static libclang libraries, so the
+        # `static` feature is not testable atm.
+        feature_runtime: [0, 1]
+        feature_extra_asserts: [0]
+
+        include:
+          # Test with extra asserts + docs just with latest llvm versions to
+          # prevent explosion
+          - os: ubuntu-latest
+            llvm_version: "9.0"
+            release_build: 0
+            no_default_features: 0
+            feature_extra_asserts: 1
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install multiarch packages
+        if: matrix.target.debian
+        run: |
+          sudo apt-get install binfmt-support qemu-user-static gcc-${{matrix.target.cross}} g++-${{matrix.target.cross}}
+          source /etc/lsb-release
+          sudo tee /etc/apt/sources.list <<EOF >/dev/null
+          deb [arch=${{matrix.target.debian}}] http://ports.ubuntu.com/ubuntu-ports/ $DISTRIB_CODENAME main
+          deb [arch=${{matrix.target.debian}}] http://ports.ubuntu.com/ubuntu-ports/ $DISTRIB_CODENAME-updates main
+          deb [arch=${{matrix.target.debian}}] http://ports.ubuntu.com/ubuntu-ports/ $DISTRIB_CODENAME-backports main
+          deb [arch=${{matrix.target.debian}}] http://ports.ubuntu.com/ubuntu-ports/ $DISTRIB_CODENAME-security main
+          EOF
+          sudo dpkg --add-architecture ${{matrix.target.debian}}
+          sudo apt-get update
+          sudo apt-get install libc6:${{matrix.target.debian}} libstdc++6:${{matrix.target.debian}}
+
+      - name: Install stable
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          target: ${{matrix.target.rust}}
+      - name: Install libtinfo
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          sudo apt-get update
+          sudo apt-get install libtinfo5
+      - name: Run all the tests (debug)
+        env:
+          GITHUB_ACTIONS_OS: ${{matrix.os}}
+          RUST_TARGET: ${{matrix.target.rust}}
+        run: cargo test --all
+      - name: Run all the tests (release)
+        env:
+          GITHUB_ACTIONS_OS: ${{matrix.os}}
+          RUST_TARGET: ${{matrix.target.rust}}
+        run: cargo test --all --release

.gitignore

@@ -0,0 +1,2 @@
+/target
+/Cargo.lock

Cargo.toml

@@ -0,0 +1,37 @@
+[package]
+name = "ebds"
+version = "0.1.0"
+edition = "2021"
+authors = ["EBDS Rust Developers"]
+description = "Messages and related types for implementing the EBDS serial communication protocol"
+keywords = ["no-std", "serial", "ebds", "bill-acceptor", "bill-validator"]
+categories = ["no-std"]
+repository = "https://github.com/ebds-rs/ebds"
+license = "MIT"
+
+[dependencies]
+bitfield = "0.14"
+log = { version = "0.4", default-features = false }
+serde = { version = "1.0", default-features = false, features = ["derive"] }
+serde_json = { version = "1.0", default-features = false, features = ["alloc"] }
+serialport = { version = "4.2", default-features = false }
+arbitrary = { version = "1", optional = true }
+parking_lot = "0.12"
+
+[features]
+default = ["sc", "usd"]
+e2e = []
+s2k = []
+sc = []
+std = []
+arbitrary = ["arbitrary/derive"]
+
+# Currency sets
+amd = []
+aud = []
+cad = []
+cny = []
+gbp = []
+jpy = []
+mxn = []
+usd = []

LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2023 EBDS Rust developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,41 @@
+# EBDS Serial Protocol
+
+This crate implements the EBDS serial protocol messages, and related types for communication with bill acceptor unit devices.
+
+The currently supported messages are implemented in the various modules in this crate, along with some common types used across multiple messages.
+
+If adding a new message, please follow the existing pattern of placing `...Command` (host-initiated) messages in `<message-type>/command.rs` files, and `...Reply` (device-initiated) messages in `<message-type>/reply.rs` files.
+
+There are some exceptions to the general rule, e.g. when the types in the documenation do not follow the `Command/Reply` naming convention.
+
+In those cases, the suffix is omitted to aid in readability when comparing with the EBDS specification.
+
+## Macros
+
+Some simple macros exist for implementing traits over the various message types. All message types should implement `MessageOps`, and all reply types should implement `OmnibusReplyOps`.
+
+`MessageOps` can be implemented with the helper macro `impl_message_ops!`, e.g. for a new `SomeNewReply` message:
+
+```rust
+use crate::impl_message_ops;
+
+pub struct SomeNewReply {
+    // For the example, we are just using a number for the length.
+    // In real implementations, please add a constant to the `len` module.
+    buf: [u8; 11],
+}
+
+impl_message_ops!(SomeNewReply);
+```
+
+This will implement the `MessageOps` trait for `SomeNewReply`, and provide all of the associated functions. Traits are how Rust does polymorphism, similar to Go's `interface` and C++'s `template`, with important differences.
+
+All of the macro implementations live in `src/macros.rs`.
+
+## Using with `std`
+
+This library is `no-std` compatible by default. To use `std`-only features, add the `std` feature to the dependency:
+
+```toml
+ebds = { version = "0.1", features = ["std"] }
+```

fuzz/.gitignore

@@ -0,0 +1,4 @@
+target
+corpus
+artifacts
+coverage