Skip to content

Commit

Permalink
chore(readme): adds container docs
Browse files Browse the repository at this point in the history
  • Loading branch information
excieve committed May 8, 2024
1 parent fc8bfa0 commit 8616d22
Showing 1 changed file with 27 additions and 5 deletions.
32 changes: 27 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,17 @@ This project is a BLE to MQTT gateway for the [Pinecil V2](https://wiki.pine64.o
It is based on the [Pinecil V2 BLE Services](https://github.com/Ralim/IronOS/blob/dev/Documentation/Bluetooth.md)
from IronOS.

While there are already [some projects](#alternative-projects) that read data from the Pinecil V2 soldering iron via BLE,
this project aims to provide a more flexible and extensible solution by publishing the data to an MQTT broker. From
there, the data can be consumed by other applications or services (e.g. Home Assistant, Grafana).
While there are already [some excellent projects](#alternative-projects) that read data from the Pinecil V2 soldering
iron via BLE, this project aims to provide a more flexible and extensible solution by publishing the data to an MQTT
broker. From there, the data can be consumed by other applications or services (e.g. Home Assistant, Grafana).

## Features

- [x] Automatically discover and connect to the Pinecil V2 soldering iron via BLE
- [x] Publish data provided by the soldering iron to an MQTT broker
- [x] Optionally authenticate with the MQTT broker
- [x] Transform raw data into human-readable values
- [x] Can be run as a standalone binary or in a container

## Pre-requisites

Expand All @@ -28,6 +29,29 @@ there, the data can be consumed by other applications or services (e.g. Home Ass

## Installation

### With containers

1. Pull the image from Docker Hub:
```shell
docker pull excieve/pinecil2mqtt:dev
```
2. Run the container (on a Linux machine) with the following command, replacing `mqtt.example.com` with your MQTT broker:
```shell
docker run -d -e P2M_MQTT_HOST=mqtt.example.com -v /run/dbus/:/run/dbus excieve/pinecil2mqtt:dev
```
3. Enjoy!

#### Caveats

The container needs access to the host's D-Bus socket to be able to communicate with BLE devices. This is
achieved by mounting the host's D-Bus socket into the container. This might not work on all platforms.

Additionally, this image is built on an Alpine Linux base image, which is known to be particular about DNS resolution.
If you encounter issues with resolving your MQTT broker's hostname, you might need to use IP address instead. This might
change in the future.

### From source

1. Clone this repository
2. Run `cargo build --release` to build the project
3. Set up a configuration file or environment variables (see [Configuration](#configuration))
Expand Down Expand Up @@ -93,7 +117,6 @@ the unique ID of your Pinecil V2 soldering iron. The payload is a JSON object th

# Roadmap

- [ ] Containerize the application and publish it to Docker Hub
- [ ] Write unit tests (I know, I know)
- [ ] Add support for the settings service read characteristics
- [ ] Add support for the settings service write characteristics via MQTT
Expand All @@ -109,4 +132,3 @@ the unique ID of your Pinecil V2 soldering iron. The payload is a JSON object th
# License

This project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for more information.

0 comments on commit 8616d22

Please sign in to comment.