Usage

Once the application is running, you can start using the SDK.

Initialization

In Setup, first make sure to setup and ensure the network connectivity (WiFi, GPRS...). Then you should initialize the SDK.

ESPAdmin::begin({
  // Required
  .httpHost = "app.esp-admin.tn",
  .deviceId = "_DEVICE_ID_",
  .apiKey = "_API_KEY_",
  .httpCert = "_HTTP_CERT_",
  .mqttCert = "_MQTT_CERT_",
  // Optional
  .resetDelayMs = 7000,
  .httpMaxResponseSize = 300,
  .httpTimeoutMs = 8000,
  .logMaxMessageSize = 200,
  .mqttTaskPriority = 5,
  .mqttTaskStackSize = 9640,
  .mqttKeepAliveSec = 30,
  .mqttNetworkTimeoutMs = 8000,
  .mqttReconnectTimeoutMs = 10000,
  .otaTaskPriority = 5,
  .otaTaskStackSize = 6928,
});

That's it you can now start using the SDK ✨

Logging

The logging API is based on the ESP_LOGI macro. Thus make sure to set DEBUG_LEVEL equal or greater than 3.

You can instantiate a logger instance of Logger class with a custom scope. A scope is a way to identify the context from which the logger is called. The logger has methods for distinct log types info, warn, success and error.

The output can be local via serial port and remote via MQTT. By default, the local logs are enabled and the remote logs are disabled.

Commands

In order to listen for incoming custom commands, you can create a handler and reference it from Command::onCustom. The handler accepts a serialized JSON message. You can parse it with the ArduinoJSON library.

void onCustomCommand(std::string message);

Command::onCustom = &onCustomCommand;

Reports

In order to send custom reports, you can use Report::send method.

Report::send({
    .type = REPORT_INFO,
    .subject = "Report's subject",
    .body = "Report's body"
  });

Variables

Config variables are accessible via Store::get(STORE_CONFIG) in serialized JSON format. You can parse it with the ArduinoJSON library. To listen for incoming config commands, you can create a handler and reference it from Command::onConfig.

void onConfigCommand(std::string message);

Command::onConfig = &onConfigCommand;

Updates

Over-the-air updates are handled internally, performed in non-blocking execution, and cause software reset on successful deployment.

Updates can be triggered manually via the web application or automatically on a CI pipeline. To build and deploy the release with GitHub Actions:

• Set the GitHub variables and secrets below.
• Add the release workflow below that will be triggered on a new GitHub release. Please note that the Tag should be in the format x.y.z or x.y.z-suffix.

Variables & Secrets

Workflow

name: Release

# Triggered when new release published
on:
  release:
    types: [published]

# Run only once, no concurrency
concurrency:
  group: production
  cancel-in-progress: true

jobs:
  build_deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/cache@v3
        with:
          path: |
            ~/.cache/pip
            ~/.platformio/.cache
          key: ${{ runner.os }}-pio
      - uses: actions/setup-python@v4
        with:
          python-version: "3.9"

      - name: Install PlatformIO Core
        run: pip install --upgrade platformio

      - name: Build PlatformIO Project
        run: pio run --environment ${{vars.PIO_ENV}}

      - name: Deploy Release
        run: |
          curl -X POST \
            -H "Api-Key:${{secrets.API_KEY}}" \
            -F "projectId=${{secrets.PROJECT_ID}}" \
            -F "version=${{github.ref_name}}" \
            -F "file=${{format('@{0}/.pio/build/{1}/firmware.bin', github.workspace, vars.PIO_ENV)}}" \
            ${{format('https://{0}/api/releases?ci=true', vars.HOST)}}