Extensions

🧩 Extensions

🎙️ Alexa

Smart-home integration.

Use app, voice control, or automations based on eg. time or presence to:

• Power on/off
• Adjust brightness

Enabled by default.

.env example:

EXTENSION_ALEXA=true

See also Home Assistant.

🏗️ Build

Firmware updates can be a hassle, the Build extension was built to change that.

Providing a nice user-interface with details about every variable in the config files, as well as copy/paste options just in case the previous project files got deleted in the past.

Enabled by default.

.env example:

EXTENSION_BUILD=true

See also OTA.

⏺️ Button

Buttons allows physical control of the device.

For devices with 2 buttons:

• Button #1:
  • Click: Power on/off
  • Hold: Brightness up/down
• Button #2:
  • Click: Next mode
  • Hold: Iterate between modes

For devices with only 1 button:

• Button #2:
  • Click: Power on/off
  • Hold: Iterate between modes

Events such as short and long press is also implemented in Home Assistant and available via the API.

secrets.h example:

#define PIN_SW1 1 // GPIO #

#define PIN_SW2 2 // GPIO #

Note: Long press any button during startup to activate the Wi-Fi hotspot.

Enabled by default when at least one of PIN_SW1 and PIN_SW2 is defined.

.env example:

EXTENSION_BUTTON=true

See also IKEA Frekvens and IKEA Obegränsad.

🤖 Home Assistant

Smart-home integration.

• Power on/off
• Brightness
• Mode
• Countdown timer
• Home thermometer
• Infrared on/off
• Message notifications
• Microphone on/off
• Playlist start/stop
• Ticker
• Various stats, control and debug data.

Requires the MQTT extension.

secrets.h example:

#define HOMEASSISTANT_TOPIC "homeassistant"

Enabled by default when the MQTT extension is enabled.

.env example:

EXTENSION_HOMEASSISTANT=true

See also Home Assistant weather mode.

🔴 Infrared

With an IR-receiver sensor, it's possible to use a remote control to control the device.

• Power on/off
• Brightness
• Mode
• Microphone on/off
• Playlist start/stop

Currently supported:

• Philips
• Sony

Use the web app to activate or deactivate this input method, it is also controllable via the Home Assistant extension.

secrets.h example:

#define PIN_IR 3 // GPIO #

Enabled by default when PIN_IR is defined.

.env example:

EXTENSION_INFRARED=true

Check out the Infrared wiki for more info.

📢 Message

Display rolling notification text messages on-demand.

Use the web app to get started.

Integrated into Home Assistant.

API example:

{
    "font": "Mini",
    "message": "Hello world!",
    "repeat": 2
}

The font and repeat parameters is optional, if omitted, the last known value will be used.

Enabled by default.

.env example:

EXTENSION_MESSAGE=true

See also Ticker.

🎙️ Microphone

Many of the modes has the ability to react to sounds, eg. syncing animations up with the music.

Use the web app to activate or deactivate this input method, it is also controllable via the Home Assistant extension.

secrets.h examples:

#define PIN_MIC 4 // GPIO #

#define MIC_FLOOR 1024 // level

Enabled by default.

.env example:

EXTENSION_MICROPHONE=true

Check out the Microphone wiki for more info.

Privacy note: there's an toggle in the user-interface to disable the microphone. It's also woth noting that the ESP32's analog inputs is capable of reading voltage levels only, not frequencies, therefore it's not possible to recording audio.

✉️ MQTT

API-endpoint.

Topic:

• Publishes: frekvens/example/+
• Subscribed: frekvens/example/+/set

API message example:

{
    "key": "value"
}

secrets.h examples:

#define MQTT_HOST "example.local"
#define MQTT_PORT 1883 // port #

#define MQTT_USER "name"
#define MQTT_KEY "[REDACTED]"

Enabled by default when MQTT_HOST is defined.

.env example:

EXTENSION_MQTT=true

✈️ OTA

Over-the-Air updates, for ESP32.

User-friendly interface for uploading firmware.bin and spiffs.bin files manually.

URL: http://example.local/#/extensions/ota

Another option is directly from the IDE/editor via Wi-Fi using espota.

platformio.ini examples:

upload_protocol = espota
upload_port = example.local

upload_flags = --auth=REDACTED

There's also optional password protection, which disables the ability to upload manually via the web app user-interface.

.env example:

OTA_KEY='REDACTED'

secrets.h example:

#define OTA_KEY_HASH "REDACTED"

Enabled by default.

.env example:

EXTENSION_OTA=true

See also Build.

▶️ Playlist

Set up a playlist of Modes that loops with a timer.

Integrated into the Button extension, long-press button #2 to activate. Can also be controlled via the Home Assistant extension.

Enabled by default.

.env example:

EXTENSION_PLAYLIST=true

💻 RESTful

Provides a RESTful API.

• Full:
  • Method: GET.
  • URL: http://example.local/api/get
• Module:
  • Method: GET or PATCH.
  • URL prefix: http://example.local/api/

API payload example:

{
    "key": "value"
}

Enabled by default.

.env example:

EXTENSION_RESTFUL=true

⏰ RTC

Reliable clock, even without Wi-Fi connectivity.

Enabled by default when a supported RTC-module is defined.

.env example:

EXTENSION_RTC=true

Check out the RTC wiki for more info.

☮️ Signal

Display drawings/icons on-demand.

API examples:

{
    "bitmap": [
        "01100110",
        "01100110",
        "00000000",
        "11000011",
        "01111110"
    ],
    "duration": 30
}

{
    "bitmap": [
        102,
        102,
        0,
        195,
        126
    ],
    "duration": 30
}

The duration parameters is optional, if omitted, the last known value will be used.

Enabled by default.

.env example:

EXTENSION_SIGNAL=true

📱 Web app

Handles the webapp user-interface located on the ESP32's SPIFFS partition.

Canonical host check:

• Method: GET.
• URL: http://example.local/canonical

Enabled by default.

.env example:

EXTENSION_WEBAPP=true

📞 WebSocket

Handles the WebSocket protocol.

Endpoint: ws://example.local/ws

API message example:

{
    "module": {
        "key": "value"
    }
}

Enabled by default. It is also required for the frontend webapp user-interface to be functional.

.env example:

EXTENSION_WEBSOCKET=true