Extensions - VIPnytt/Frekvens GitHub Wiki

🧩 Extensions

Accessories: Button | Infrared | Microphone | Photocell | RTC | Status LED

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

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

Smart-home: Alexa | Home Assistant | MQTT

Tools: Heap | OTA | Screenshot

🎤 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
  5. Discover

[!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.

🔴 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 example:

{
    "active": true,
    "playlist": [
        {
            "mode": "Clock",
            "duration": 20
        },
        {
            "mode": "Ticker",
            "duration": 30
        },
        {
            "mode": "Weather",
            "duration": 10
        }
    ]
}

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.

📜 Screenshot

Take screenshots of the display.

Configure in .env:

EXTENSION_SCREENSHOT='true'

See also Web app.

📜 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'

🟢 Status LED

Provides low-level status of the device. Solid in normal conditions, blinks about once a second on warnings (e.g. Wi-Fi connectivity issues) and rapidly on errors.

Configure in .env:

EXTENSION_STATUSLED='true'

Check out the Status LED wiki for more info.

📱 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'