mirror of
https://github.com/fossasia/badgemagic-rs
synced 2025-06-23 23:33:58 +00:00
c273d4cbfc
Adds a new crate feature `ble` that allows for transfering badge configurations over Bluetooth Low Energy instead of USB. Expands the CLI to allow for specification of the transport protocol, either USB or BLE. The BLE library uses async rust requiring to add tokio as a async runtime to the CLI.
131 lines
3.8 KiB
Markdown
131 lines
3.8 KiB
Markdown
[](../../actions/workflows/ci.yaml)
|
|
|
|
# Badge Magic in Rust
|
|
|
|
Library and CLI to configure LED badges.
|
|
|
|
## Installation
|
|
|
|
As of now there are no proper releases (with version numbers) of this tool.
|
|
|
|
The latest commit on the main branch just gets build and released automatically.
|
|
|
|
Download the prebuild program for one of the following operating systems:
|
|
|
|
- [Linux (GNU / 64 bit)](../../releases/latest/download/badgemagic.x86_64-unknown-linux-gnu)
|
|
- [Windows (64 bit)](../../releases/latest/download/badgemagic.x86_64-pc-windows-msvc.exe)
|
|
- [MacOS (Intel)](../../releases/latest/download/badgemagic.x86_64-apple-darwin)
|
|
- [MacOS (M1, etc.)](../../releases/latest/download/badgemagic.aarch64-apple-darwin)
|
|
|
|
```sh
|
|
# After the download rename the file to `badgemagic`
|
|
mv badgemagic.<target> badgemagic
|
|
|
|
# Make the program executable (linux / macOS only)
|
|
chmod +x badgemagic
|
|
|
|
# Test that it works
|
|
./badgemagic --help
|
|
```
|
|
|
|
> Note: The windows and macOS build is not actively tested. Please try it out and report back whether it worked or any problems that might occour.
|
|
|
|
If your system is not listed above (Linux / Windows on ARM, musl, etc.) or you want to do it anyway, you can install this tool from source:
|
|
|
|
```sh
|
|
cargo install --git https://github.com/fossasia/badgemagic-rs --features cli
|
|
badgemagic --help
|
|
```
|
|
|
|
Or clone the repo and run the CLI:
|
|
```sh
|
|
git clone https://github.com/fossasia/badgemagic-rs
|
|
cd badgemagic-rs
|
|
cargo run --features cli -- --help
|
|
```
|
|
|
|
## Usage
|
|
|
|
Execute the `badgemagic` tool and pass the file name of your configuration file alongside the mode of transport (USB or Bluetooth Low Energy).
|
|
Depending on how you installed the tool:
|
|
|
|
```sh
|
|
# Downloaded from release page
|
|
./badgemagic config.toml
|
|
|
|
# Installed with cargo install
|
|
badgemagic config.toml
|
|
|
|
# Run from git repository
|
|
cargo run --features cli -- config.toml
|
|
```
|
|
|
|
The above command will read your configuration from a file named `config.toml` in the current directory.
|
|
The transport mode can be either `--transport usb` or `--transport ble` for transferring the message via Bluetooth Low Energy.
|
|
Usage of BLE on macOS requires special permissions, which is explained in more detail [here](https://github.com/deviceplug/btleplug#macos).
|
|
|
|
## Configuration
|
|
|
|
You can have a look at the example configurations in the [`demo` directory](demo).
|
|
|
|
The TOML configuration consists of up to 8 message sections starting with `[[message]]`.
|
|
|
|
Each message can have the following options:
|
|
```toml
|
|
[[message]]
|
|
# Enable blink mode
|
|
blink = true
|
|
|
|
# Show a dotted border arround the display
|
|
border = true
|
|
|
|
# Set the update speed of the animations (0 to 7)
|
|
speed = 6
|
|
|
|
# Set the display animation (left, right, up, down, center, fast, drop, curtain, laser)
|
|
mode = "left"
|
|
|
|
# The text to show on the display
|
|
text = "Lorem ipsum dolor sit amet."
|
|
```
|
|
|
|
You can omit options you don't need:
|
|
```toml
|
|
[[message]]
|
|
mode = "center"
|
|
text = "Hello"
|
|
```
|
|
|
|
If you want you can "draw" images as ASCII art (`_` = Off, `X` = On):
|
|
```toml
|
|
[[message]]
|
|
mode = "center"
|
|
bitstring = """
|
|
___XXXXX___
|
|
__X_____X__
|
|
_X_______X_
|
|
X__XX_XX__X
|
|
X__XX_XX__X
|
|
X_________X
|
|
X_XX___XX_X
|
|
X__XXXXX__X
|
|
_X__XXX__X_
|
|
__X_____X__
|
|
___XXXXX___
|
|
"""
|
|
```
|
|
|
|
You just replace the `text` option with `bitstring`. All other options (e.g. `border`, `blink`) still work and can be combined with a custom image.
|
|
|
|
## License
|
|
|
|
Licensed under either of
|
|
|
|
- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
|
|
- MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
|
|
|
|
at your option.
|
|
|
|
### Contribution
|
|
|
|
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
|