Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/becem-gharbi/esp-ota-cicd
A complete CI/CD solution for ESP32
https://github.com/becem-gharbi/esp-ota-cicd
ci-cd esp32 github ota
Last synced: 3 months ago
JSON representation
A complete CI/CD solution for ESP32
- Host: GitHub
- URL: https://github.com/becem-gharbi/esp-ota-cicd
- Owner: becem-gharbi
- License: mit
- Created: 2023-05-26T10:45:51.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-07-25T05:16:28.000Z (6 months ago)
- Last Synced: 2024-10-12T05:11:46.482Z (3 months ago)
- Topics: ci-cd, esp32, github, ota
- Language: C++
- Homepage:
- Size: 51.8 KB
- Stars: 3
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# ESP OTA CI/CD
> [!TIP]
> To visually apply the OTA update, it's recommended to use [ESP Admin](https://esp-admin.tn/) which is a web platform for remote management of ESP32 microcontrollers.
This project provides a CI/CD pipeline for seamless remote software updates to *ESP32*, including a PlatformIO library that automatically handles deployment.
## Requirements
- Platform `espressif32`
- IDE `PlatformIO`
- Framework `Arduino`
## How it works
- Upon a new software release, depending on the CI/CD tool used, a workflow is triggered.
- The code is compiled to generate the executable binary.
- The executable is uploaded to an S3-compatible bucket.
- An MQTT message is sent to the release topic on which `ESP32` is subscribed. The message contains the firmware version and the download URL.
- The library receives the message and checks the version against the running version.
- If the received firmware is newer, the library downloads it and performs the necessary flashing process.
## CI/CD settings
The settings depend on the CI/CD tool used. An integration with `Github Actions` is provided via `.github/workflows/release.yml`.
The variables and secrets **should** be set as described in [docs](https://docs.github.com/en/actions/learn-github-actions/variables).
### Secrets
| **Secrets** | **Notes** |
| -------------------- | ---------------------------------------------------------------------------------- |
| MQTT_HOST | The MQTT host, eg `broker.hivemq.com` |
| MQTT_PORT | The MQTT TCP port, eg `1883` |
| MQTT_SECURE | Whether a default SSL configuration is used, can be set to `false` or ` ` for true |
| MQTT_VERSION | The MQTT version can be set to `3` or `5` |
| MQTT_USER | The username for MQTT authentication |
| MQTT_PASSWORD | The password for MQTT authentication |
| S3_ACCESS_KEY_ID | The S3 client ID |
| S3_SECRET_ACCESS_KEY | The S3 client secret |
| S3_ENDPOINT_URL | The S3 endpoint, check provider |
| S3_REGION | The S3 region, check provider |
| S3_BUCKET | The S3 bucket used, should be public |
| S3_PUBLIC_URL | The public URL of the provided bucket |
### Variables
| **Variables** | **Notes** |
| -------------- | ------------------------------------------------------------- |
| MQTT_PUB_TOPIC | The MQTT topic to which the release message will be published |
| PIO_ENV | Environment to build, check `platformio.ini` |
## Library usage
To automatically deploy the new firmware, this project provides a PlatformIO library
```
pio pkg install --library "bg-dev/OtaCicd"
```
The library exposes `OtaCicd` class which implements an MQTT client and an OTA handler with secure HTTP connections. You just need to initialize it
```C++
esp_mqtt_client_config_t mqttConfig = {
.uri = mqtt_uri,
.client_id = mqtt_client_id,
.username = mqtt_user,
.password = mqtt_password,
.cert_pem = mqtt_cert_pem};
OtaCicd::init(s3CertPem, releaseTopic, mqttConfig);
```
In case you want to implement an MQTT client independently, you can call the `start` method upon receiving a release message.
```C++
OtaCicd::init(s3CertPem);
OtaCicd::start(message);
```
## License
[MIT License](./LICENSE)