peach-oled
OLED microservice module for PeachCloud. Write to a 128x64 OLED display with SDD1306 driver (I2C) using JSON-RPC over http.
JSON-RPC API
| Method | Parameters | Description |
|---|---|---|
clear |
Clear the display buffer | |
draw |
bytes, width, height, x_coord, y_coord |
Draw graphic to display buffer for given byte array, dimensions and co-ordinates |
flush |
Flush the display | |
ping |
Respond with success if microservice is running |
|
power |
on |
Toggle the display (memory is retained while off) |
write |
x_coord, y_coord, string, font_size |
Write message to display buffer for given co-ordinates using given font size |
| Font Sizes |
|---|
6x8 |
6x12 |
8x16 |
12x16 |
Environment
The JSON-RPC HTTP server address and port can be configured with the PEACH_OLED_SERVER environment variable:
export PEACH_OLED_SERVER=127.0.0.1:5000
When not set, the value defaults to 127.0.0.1:5112.
Logging is made available with env_logger:
export RUST_LOG=info
Other logging levels include debug, warn and error.
Setup
Clone this repo:
git clone https://github.com/peachcloud/peach-oled.git
Move into the repo and compile:
cd peach-oled
cargo build --release
Run the binary:
./target/release/peach-oled
Debian Packaging
A systemd service file and Debian maintainer scripts are included in the debian directory, allowing peach-oled to be easily bundled as a Debian package (.deb). The cargo-deb crate can be used to achieve this.
Install cargo-deb:
cargo install cargo-deb
Move into the repo:
cd peach-oled
Build the package:
cargo deb
The output will be written to target/debian/peach-oled_0.1.0_arm64.deb (or similar).
Build the package (aarch64):
cargo deb --target aarch64-unknown-linux-gnu
Install the package as follows:
sudo dpkg -i target/debian/peach-oled_0.1.0_arm64.deb
The service will be automatically enabled and started.
Uninstall the service:
sudo apt-get remove peach-oled
Remove configuration files (not removed with apt-get remove):
sudo apt-get purge peach-oled
Example Usage
Write Text to the OLED Display
With microservice running, open a second terminal window and use curl to call server methods:
curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "write", "params" : {"x_coord": 0, "y_coord": 0, "string": "Welcome to PeachCloud", "font_size": "6x8" }, "id":1 }' 127.0.0.1:5112
Server responds with:
{"jsonrpc":"2.0","result":success","id":1}
OLED will remain blank because no flush command has been issued.
Write to the second line of the display:
curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "write", "params" : {"x_coord": 0, "y_coord": 8, "string": "Born in cypherspace", "font_size": "6x12" }, "id":1 }' 127.0.0.1:5112
Flush the display:
curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "flush", "id":1 }' 127.0.0.1:5112
OLED display shows:
Welcome to PeachCloud!
Born in cypherspace
Validation checks are performed for all three parameters: x_coord, y_coord and string. An appropriate error is returned if the validation checks are not satisfied:
{"jsonrpc":"2.0","error":{"code":1,"message":"Validation error: coordinate x out of range 0-128: 129."},"id":1}
{"jsonrpc":"2.0","error":{"code":1,"message":"validation error","data":"y_coord not in range 0-57"},"id":1}
{"jsonrpc":"2.0","error":{"code":1,"message":"Validation error: string length 47 out of range 0-21."},"id":1}
An error is returned if one or all of the expected parameters are not supplied:
{"jsonrpc":"2.0","error":{"code":-32602,"message":"Invalid params: missing field font_size."},"id":1}
Draw Graphic to the OLED Display
With microservice running, open a second terminal window and use curl to call server methods:
curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "draw", "params" : {"bytes": [30, 0, 33, 0, 64, 128, 128, 64, 140, 64, 140, 64, 128, 64, 64, 128, 33, 0, 30, 0], "width": 10, "height": 10, "x_coord": 32, "y_coord": 32}, "id":1 }' 127.0.0.1:5112
Server responds with:
{"jsonrpc":"2.0","result":success","id":1}
OLED will remain blank because no flush command has been issued.
Flush the display:
curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "flush", "id":1 }' 127.0.0.1:5112
OLED display shows a 10x10 graphic of a dot inside a circle.
No validation checks are currently performed on the parameters of the draw RPC, aside from type-checks when the parameters are parsed.
Clear the Display
curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "clear", "id":1 }' 127.0.0.1:5112
Server responds with:
{"jsonrpc":"2,0","result":"success","id":1}
Licensing
AGPL-3.0
