Skip to content

Extensions

Jump to bottom
github-actions[bot] edited this page Dec 3, 2025 · 14 revisions

🧩 Extensions

Accessories: Button | Infrared | Microphone | Photocell | RTC

APIs: MQTT | RESTful | Server-Sent Events | WebSocket

Interactive: Button | Message | Playlist | Signal | Web app

Smart-home: Alexa | Home Assistant | MQTT

Tools: Heap | OTA

🎤 Alexa

Smart-home integration.

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

  • Power on/off
  • Adjust brightness

In the Alexa app, navigate to:

  1. Devices
  2. Add Device
  3. Other
  4. Wi-Fi

Note

An Amazon Alexa device is required.

Configure in .env:

EXTENSION_ALEXA='true'

See also Home Assistant.

⏺️ Button

Buttons allows physical control of the device.

For devices with 2 buttons:

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

When the Mode button is the only button, it serves a dual purpose:

  • #2: Mode button
    • 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.

Tip

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

Configure in secrets.h:

#define PIN_SW1 1 // Power button
#define PIN_SW2 2 // Mode button

Configure in .env:

EXTENSION_BUTTON='true'

See also IKEA Frekvens and IKEA Obegränsad.

💾 Heap

Reports memory usage.

Integrated into the Home Assistant extensions.

Configure in .env:

EXTENSION_HEAP='true'

🧬 Home Assistant

Smart-home integration.

Key supported features include:

  • Power, brightness, and mode selection.
  • Control over extensions like the microphone and infrared receiver.
  • Access to various statistics, debug data, and advanced settings.

Configure in .env:

EXTENSION_HOMEASSISTANT='true'

Important

The Home Assistant MQTT integration is required.

See also Home Assistant weather mode.

🔴 Infrared

By adding an IR receiver, you can use a remote control, like a TV remote, to operate the device. This gives you the flexibility to use an existing remote you may already own.

  • Display brightness: up/down
    • Philips: Volume ➕➖
    • Sony: Volume ➕➖
  • Display power: toggle
    • Philips: Power ⏻
    • Sony: Power ⏻
  • Microphone: toggle
    • Philips: Mute 🔇
    • Sony: Mute 🔇
  • Mode: next/previous
    • Philips: Title ⏮️⏭️ Album ⏪⏩
    • Sony: Program ➕➖ Previous ⏮️ Next ⏭️ Rewind ⏪ Fast forward ⏩
  • Photocell: toggle
    • Philips: DIM
    • Sony: SCENE
  • Playlist: start/stop
    • Philips: Play/Pause ⏯️ Stop ⏹️
    • Sony: Play ▶️ Pause ⏸️ Stop ⏹️

Tip

Use the Web app or Home Assistant to activate or deactivate this input method.

API payload example:

{
    "active": true
}

Configure in secrets.h:

#define PIN_IR 3 // Receiver

Configure in .env:

EXTENSION_INFRARED='true'

Check out the Infrared wiki for more info.

📢 Message

Display rolling notification text messages on-demand.

Use the Web app to send messages, or set up automations via Home Assistant.

API payload example:

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

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

Configure in .env:

EXTENSION_MESSAGE='true'

See also Ticker.

🎙️ Microphone

If the device isn’t already equipped with a Microphone, adding one gives many modes the ability to react to sounds, eg. syncing animations up with the music.

Tip

Use the Web app or Home Assistant to control this input method.

API payload example:

{
    "active": true,
}

Configure in secrets.h:

#define PIN_MIC 4 // Amplifier

Configure in .env:

EXTENSION_MICROPHONE='true'

Check out the Microphone wiki for hardware instructions.

✉️ MQTT

API-endpoint.

Topic:

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

API message example:

{
    "key": "value"
}

Configure in secrets.h:

#define MQTT_HOST "mqtt.local"
#define MQTT_PORT 1883
#define MQTT_USER "name"
#define MQTT_KEY "password"

Configure in .env:

EXTENSION_MQTT='true'

✈️ OTA

Over-the-Air updates, for ESP32.

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

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

Configure in platformio.ini:

upload_protocol = espota
upload_port = frekvens.local
;upload_flags = --auth=secret

Note

The optional password protection removes the ability to upload manually via the Web app user-interface.

Configure in .env:

OTA_KEY='secret'
EXTENSION_OTA='true'

🔆 Photocell

By adding a Photocell, you’ll get automatic ambient brightness adaption.

Tip

Use the Web app or Home Assistant to control this input method.

API payload example:

{
    "active": true,
}

Configure in secrets.h:

#define PIN_LDR 5 // Bridge

Configure in .env:

EXTENSION_PHOTOCELL='true'

Check out the Photocell wiki for hardware instructions.

▶️ Playlist

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

Integrated into the Web app and Home Assistant extensions.

API payload examples:

{
    "active": true,
}

Configure in .env:

EXTENSION_PLAYLIST='true'

↔️ RESTful

Provides a RESTful API.

  • Full:
    • Method: GET
    • URL: http://frekvens.local/restful/
  • Module:
    • Method: GET or PATCH
    • URL: http://frekvens.local/restful/module

API payload example:

{
    "key": "value"
}

Configure in .env:

EXTENSION_RESTFUL='true'

See also Server-Sent Events.

⏰ RTC

By adding an RTC-module you’ll get reliable clock, even without Wi-Fi connectivity.

Configure in .env:

EXTENSION_RTC='true'

Check out the Real-Time Clock wiki for hardware instructions.

📜 Server-Sent Events

Real-time event stream API.

Endpoint: http://frekvens.local/server-sent%20events

Configure in .env:

EXTENSION_SERVERSENTEVENTS='true'

See also RESTful.

☮️ Signal

Display drawings/icons on-demand.

API payload 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.

Configure in .env:

EXTENSION_SIGNAL='true'

📱 Web app

Handles the ./webapp user-interface located in the filesystem partition.

Configure in .env:

EXTENSION_WEBAPP='true'

Note

Requires WebSocket.

📞 WebSocket

Handles the WebSocket protocol.

Endpoint: ws://frekvens.local/websocket

API message example:

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

Configure in .env:

EXTENSION_WEBSOCKET='true'

🤝 Contributions are welcome!

To help improve this wiki, open a pull request to docs/wiki.

📌 Getting Started

💡 Devices

📦 Modules

➕ Accessories

🗃️ Miscellaneous

Clone this wiki locally