API

Use the HTTP REST API on port 80 or MQTT to control PixelIt. Both interfaces can be active at the same time. This page describes firmware 2.6.0.

TIP

If you use the Node-RED or ioBroker integration, you don't need to use the API directly.

Interfaces

REST

HTTP endpoints are listed below. Send screen and configuration payloads as JSON objects using Content-Type: application/json.

MQTT

The default MQTT prefix is pixelit/ and can be changed in the WebUI. In the examples below, <MasterTopic> means the prefix without its trailing slash, so <MasterTopic>/setScreen becomes pixelit/setScreen. Do not add a second slash.

Enable mqttUseDeviceTopic to also address a single device at <MasterTopic>/<hostname>/setScreen. Devices using the same master topic receive the same master-topic commands.

Enable both MQTT and mqttHAdiscoverable to make the device discoverable via Home Assistant. See the Home Assistant guide for setup, discovery limitations and automation examples.

MQTT query topics (getLuxsensor, getMatrixinfo, getConfig) require a non-empty JSON object as their request payload in 2.6.0; empty payloads and {} are rejected by the shared parser. Responses are published on the corresponding sensor, matrix-info or config topic.

WebSocket

The WebUI and ioBroker receive live updates over ws://<device-ip>:81. Status messages wrap their data under sysinfo, luxsensor, sensor, config, buttons or telemetry.

Commands use a wrapper, unlike REST and MQTT screen payloads. For example, activate the clock with:

{"setScreen":{"clock":{}}}

Use compact JSON serialization without extra whitespace: firmware 2.6.0 compares incoming message length with the parsed object's compact length and rejects mismatches. setConfig wraps a configuration object and restarts the device after saving. Reset commands are {"wifiReset":true} and {"factoryReset":true}.

Forced screens

To temporarily protect screen content from ordinary incoming screen commands, send a positive forcedDuration in milliseconds alongside setScreen over WebSocket:

{"forcedDuration":5000,"setScreen":{"text":{"textString":"Alert","bigFont":false,"scrollText":false,"centerText":true,"position":{"x":0,"y":1},"hexColor":"#FFFFFF"}}}

This example protects the text for five seconds. The duration applies to text, bitmap, bitmap animation and bar content, not a clock-only command. Another forced screen can replace it. Sleep, brightness, auto-brightness, GPIO and sound controls are processed separately from the content lock. The clock fallback also runs separately; disable automatic fallback if it would interrupt the forced screen.

Expiry only allows new screen commands again; it does not restore the previous screen. forcedDuration is a WebSocket wrapper field, not a field supported by REST or MQTT screen payloads.

Live matrix view and logs

The firmware also sends these WebSocket messages:

Message	Payload
liveview	A string of six hexadecimal RGB digits per pixel, in row order from the top-left corner. A 32×8 matrix has 256 pixels and 1536 hexadecimal characters. This is RGB888, unlike the RGB565 arrays used by screen commands.
log	An object containing timeStamp, function and message. Timestamps use the device's current time.

The live-view buffer is checked every 250 ms and sent when its contents change. For example, {"liveview":"..."} represents the message shape only; replace ... with the complete pixel string when decoding it. Log messages are emitted as events occur.

The telemetry message is sent when a WebSocket client connects. The command {"sendTelemetry":true} resets the telemetry send timer; an upload follows when telemetry is enabled. See Telemetry and update notifications.

Endpoints

The following endpoints are available:

Endpoint	Description	Details
screen	Show screen on device	Details
brightness	Get brightness; set via screen	Details
buttons	Get button states	Details
luxsensor	Get lux sensor value	Details
sensor	Get sensor values	Details
state	Get state (MQTT only)	Details
matrixinfo	Get matrix info	Details
config	Get or set config	Details
wifireset	WiFi reset	Details
factoryreset	Reset device to factory defaults	Details

Screen

Send one screen payload to /api/screen or <MasterTopic>/setScreen. Fields such as text, bitmap and clock describe the screen; brightness, sleepMode, setGpio and sound control device behavior.

HTTP Endpoint [POST]

/api/screen

MQTT Topic [PUBLISH]

<MasterTopic>/setScreen

You must combine all elements in one call that are to be displayed as one screen.

Example call:

Example call:

Calling the internal clock with a fade animation:

{
  "switchAnimation": {
    "aktiv": true,
    "animation": "fade"
  },
  "clock": {
    "switchAktiv": true,
    "withSeconds": false,
    "switchSec": 6,
    "hexColor": "#1E00FF"
  }
}

Call fade animation, image and text:

{
  "switchAnimation": {
    "aktiv": true,
    "animation": "fade"
  },
  "bitmap": {
    "data": [
      0, 0, 0, 21855, 0, 0, 0, 0, 0, 0, 0, 21855, 0, 0, 0, 0, 0, 0, 21855,
      21855, 21855, 0, 0, 0, 0, 0, 21855, 21855, 21855, 0, 0, 0, 0, 693, 1055,
      1055, 65535, 44735, 0, 0, 0, 693, 1055, 65535, 65535, 44735, 0, 0, 0, 693,
      1055, 1055, 65535, 21855, 0, 0, 0, 0, 693, 1055, 21855, 0, 0, 0
    ],
    "position": {
      "x": 0,
      "y": 0
    },
    "size": {
      "width": 8,
      "height": 8
    }
  },
  "text": {
    "textString": "59%",
    "bigFont": false,
    "scrollText": false,
    "scrollTextDelay": 0,
    "centerText": true,
    "position": {
      "x": 7,
      "y": 1
    },
    "hexColor": "#1E00FF"
  }
}

Text

---

The following special characters are supported: € ← ↑ → ↓ ★ ♥ ↧ 🚗 😀 📁 📄

{
  "text": {
    "textString": "Test It :D",
    "bigFont": false,
    "scrollText": "auto",
    "scrollTextDelay": 20,
    "centerText": false,
    "position": {
      "x": 8,
      "y": 1
    },
    "color": {
      "r": 255,
      "g": 255,
      "b": 255
    },
    "hexColor": "#FFFFFF"
  }
}

Parameter	Type	Values	Description
textString	String		Required. Displayed Text
bigFont	Boolean	false / true	false: small text; true: large text
scrollText	Boolean / String	true / false / auto	Enable scrolling; auto scrolls long text
scrollTextDelay	Integer	Positive milliseconds	Optional delay in milliseconds; otherwise uses scrollTextDefaultDelay
centerText	Boolean	true / false	Include an explicit value for predictable rendering
position	JSON	{"x":8, "y":1}	Include an explicit value for predictable rendering
color	JSON	{"r":255, "g":255, "b":255}	Use this or hexColor
hexColor	String	#FFFFFF	Alternative to color

Use JSON booleans (false or true) for text.bigFont, without quotation marks. Configure the internal clock fonts separately using fatFont and largeFont; see Clock.

Sleep Mode

---

Send sleepMode through the screen endpoint to turn the display off or on. While asleep, the device does not render new screen content. A message containing sleepMode also skips new screen content, even when its value is false.

To wake the display and show a new screen, first send {"sleepMode": false}, then send the new screen in a separate request without sleepMode. Waking restores the last saved screen when one is available.

Enabling sleepMode turns off the matrix display; it does not put the ESP8266 or ESP32 into deep sleep.

{
  "sleepMode": false
}

Parameter	Type	Values	Description
sleepMode	Boolean	true / false	When active sleepMode disables the rendering of new screens

Brightness

---

Set the display brightness while awake. Automatic brightness control can change it again; use the configuration API to save a persistent setting.

{
  "brightness": 125
}

Parameter	Type	Values	Description
brightness	Integer	0 - 255	Sets the brightness

Auto-Brightness

---

Enable or disable automatic brightness control without saving the configuration.

{
  "autobrightness": false
}

Parameter	Type	Values	Description
autobrightness	Boolean	true / false	Temporary enable/disable the auto brightness feature

Switch Animation

---

{
  "switchAnimation": {
    "aktiv": true,
    "animation": "fade"
  }
}

Call bitmapWipe example

{
  "switchAnimation": {
    "aktiv": true,
    "animation": "bitmapWipe",
    "data": [65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535],
    "width": 1
  }
}

Parameter	Type	Values	Description
aktiv	Boolean	true / false
animation	String	fade / coloredBarWipe / zigzagWipe / bitmapWipe / random	bitmapWipe call example
data	Integer Array	RGB565 pixel values	Required for bitmapWipe; provide width × 8 RGB565 values
width	Integer	1 - 32	Required for bitmapWipe height always needs to be 8

Clock

---

An object such as {"clock": {}} activates the device clock. The legacy show field is ignored in 2.6.0. Omitted clock options retain their current settings. Send text or bitmap content to replace the clock display.

{
  "clock": {
    "switchAktiv": true,
    "withSeconds": true,
    "switchSec": 5,
    "drawWeekDays": true,
    "color": {
      "r": 255,
      "g": 255,
      "b": 255
    },
    "hexColor": "#FFFFFF"
  }
}

Parameter	Type	Values	Description
switchAktiv	Boolean	true / false	Switch clock/date
switchSec	Integer	Positive seconds	Interval between clock/date changes; used when switching is enabled
withSeconds	Boolean	true / false	Show seconds
blinkAnimated	Boolean	true / false	Animate the clock separator
fatFont	Boolean	true / false	Select the fat clock font
largeFont	Boolean	true / false	Select the large clock font
drawWeekDays	Boolean	true / false	Draw weekdays
color	JSON	{"r":255, "g":255, "b":255}	RGB color (or hexColor)
hexColor	String	#FFFFFF	Alternative to color

Bitmap

---

Provide one RGB565 integer per pixel, in row order (width × height values). The example is a solid white 8×8 bitmap.

{
  "bitmap": {
    "data": [
      65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
      65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
      65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
      65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
      65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
      65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
      65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
      65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535
    ],
    "position": {
      "x": 0,
      "y": 0
    },
    "size": {
      "width": 8,
      "height": 8
    }
  }
}

Parameter	Type	Values	Description
data	Integer Array	RGB565 pixel values	Required
position	JSON	{"x":0, "y":0}	Required
size	JSON	{"width":8, "height":8}	Required

Bitmaps

---

Use bitmaps to display multiple static bitmaps on one screen. Each bitmap needs width × height RGB565 values.

Limitations

When displaying multiple bitmaps, animated bitmaps, scrolling or text are not supported!

{
  "bitmaps": [
    {
      "data": [
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535
      ],
      "position": {
        "x": 0,
        "y": 0
      },
      "size": {
        "width": 8,
        "height": 8
      }
    },
    {
      "data": [
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535
      ],
      "position": {
        "x": 8,
        "y": 0
      },
      "size": {
        "width": 8,
        "height": 8
      }
    },
    {
      "data": [
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535
      ],
      "position": {
        "x": 16,
        "y": 0
      },
      "size": {
        "width": 8,
        "height": 8
      }
    },
    {
      "data": [
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535
      ],
      "position": {
        "x": 24,
        "y": 0
      },
      "size": {
        "width": 8,
        "height": 8
      }
    }
  ]
}

Parameter	Type	Values	Description
data	Integer Array	RGB565 pixel values	Required
position	JSON	{"x":0, "y":0}	Required
size	JSON	{"width":8, "height":8}	Required

Bitmap Animation

---

Use 1–9 frames, each containing exactly 64 RGB565 values for an 8×8 image. The firmware has ten storage slots and uses an unused slot as an end marker. Do not send 32×8 frames: although size is read, only 64 pixels per frame are stored in 2.6.0. Avoid RGB565 value 2 as the first pixel of a frame, because it is used as the end marker. The example cycles through white, blue and red.

{
  "bitmapAnimation": {
    "data": [
      [
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535,
        65535, 65535, 65535, 65535, 65535, 65535, 65535, 65535
      ],
      [
        31, 31, 31, 31, 31, 31, 31, 31,
        31, 31, 31, 31, 31, 31, 31, 31,
        31, 31, 31, 31, 31, 31, 31, 31,
        31, 31, 31, 31, 31, 31, 31, 31,
        31, 31, 31, 31, 31, 31, 31, 31,
        31, 31, 31, 31, 31, 31, 31, 31,
        31, 31, 31, 31, 31, 31, 31, 31,
        31, 31, 31, 31, 31, 31, 31, 31
      ],
      [
        63488, 63488, 63488, 63488, 63488, 63488, 63488, 63488,
        63488, 63488, 63488, 63488, 63488, 63488, 63488, 63488,
        63488, 63488, 63488, 63488, 63488, 63488, 63488, 63488,
        63488, 63488, 63488, 63488, 63488, 63488, 63488, 63488,
        63488, 63488, 63488, 63488, 63488, 63488, 63488, 63488,
        63488, 63488, 63488, 63488, 63488, 63488, 63488, 63488,
        63488, 63488, 63488, 63488, 63488, 63488, 63488, 63488,
        63488, 63488, 63488, 63488, 63488, 63488, 63488, 63488
      ]
    ],
    "animationDelay": 20,
    "rubberbanding": false,
    "limitLoops": 0
  }
}

Parameter	Type	Values	Description
data	Array of Integer Arrays	One array of 64 RGB565 values per frame	Exactly 64 RGB565 values per frame; see the limits above
animationDelay	Integer	Milliseconds	Required Higher is a slower animation
rubberbanding	Boolean	true / false	Should the animation run back and forth
limitLoops	Integer	0 or a positive count	0 repeats indefinitely; a positive value limits playback
position	JSON	{"x":0, "y":0}	Position

Bar

---

{
  "bar": {
    "position": {
      "x": 0,
      "y": 0,
      "x2": 0,
      "y2": 0
    },
    "color": {
      "r": 255,
      "g": 255,
      "b": 255
    },
    "hexColor": "#FFFFFF"
  }
}

Parameter	Type	Values	Description
position	JSON	{"x":0, "y":0,"x2":1, "y2":7}	Include an explicit value for predictable rendering
color	JSON	{"r":255, "g":255, "b":255}	RGB color (or hexColor)
hexColor	String	#FFFFFF	Alternative to color

Bars

---

Here you can pass an array of bars to draw several on one screen.

{
  "bars": [
    {
      "position": {
        "x": 0,
        "y": 0,
        "x2": 0,
        "y2": 0
      },
      "color": {
        "r": 255,
        "g": 255,
        "b": 255
      },
      "hexColor": "#FFFFFF"
    }
  ]
}

Parameter	Type	Values	Description
position	JSON	{"x":0, "y":0,"x2":1, "y2":7}	Include an explicit value for predictable rendering
color	JSON	{"r":255, "g":255, "b":255}	RGB color (or hexColor)
hexColor	String	#FFFFFF	Alternative to color

Set GPIO

gpio is the GPIO number, not a D1 mini D-label. Select a free output-capable pin that is not used by the matrix, sensors or flash. Up to four GPIO reset timers can be active. Without duration, the output remains at the requested level.

{
  "setGpio": {
    "gpio": 14,
    "set": true,
    "duration": 500
  }
}

Parameter	Type	Values	Description
gpio	Integer	E.g. 14	Required GPIO of the ESP
set	Boolean	true / false	Required
duration	Integer	Positive milliseconds	Optional timeout after which the GPIO is set LOW

Sound

---

A DFPlayer Mini must be connected and configured. Firmware supports play, pause, next and previous; it does not implement stop. Volume and playback changes are more reliable as separate requests on some modules.

Option 1

Supply folder and file to call the DFPlayer library's folder-play command. Use numbered directories and files, for example 01/001.mp3. Do not rely on next and previous to remain within that folder.

{
  "sound": {
    "volume": 20,
    "control": "play",
    "folder": 1,
    "file": 1
  }
}

Parameter	Type	Values	Description
volume	Integer	0 - 30	Optional volume setting
control	String	play / pause	Required for playback commands; omit for volume-only changes
folder	Integer	1 - 99	Required
file	Integer	1 - 255	Required for play

Option 2

Omit folder (or use 0) to select a track using the library's play(file) command. This uses the DFPlayer's track index, which can depend on the order files were copied to the card. It is not the dedicated /MP3/0001.mp3 folder command. Prepare the card according to the DFRobot documentation (opens new window). next and previous use the module's track navigation.

{
  "sound": {
    "volume": 20,
    "control": "play",
    "file": 1
  }
}

Parameter	Type	Values	Description
volume	Integer	0 - 30	Optional volume setting
control	String	play / pause / next / previous	Required for playback commands; omit for volume-only changes
file	Integer	1 - 3000	Required for play

Brightness

HTTP Endpoint [GET]

/api/brightness

Query the current brightness. To set it, use the screen brightness field. With MQTT, subscribe to <MasterTopic>/matrixinfo to get the current brightness.

The response has the following structure:

{
  "brightness_255": 20,
  "brightness": 7,
  "hostname": "PixelIt"
}

Buttons

HTTP Endpoint [GET]

/api/buttons

The HTTP response has the following structure:

{
  "leftButton": "false",
  "middleButton": "true",
  "rightButton": "false",
  "hostname": "PixelIt"
}

MQTT Topic [SUBSCRIBE]

<MasterTopic>/buttons/#
<MasterTopic>/buttons/button0
<MasterTopic>/buttons/button1
<MasterTopic>/buttons/button2

Each button topic publishes the plain text payload true or false (without quotes or a JSON object).

Lux Sensor

HTTP Endpoint [GET]

/api/luxsensor

MQTT Topic [PUBLISH]

<MasterTopic>/getLuxsensor

MQTT Topic [SUBSCRIBE]

<MasterTopic>/luxsensor

The response has the following structure:

{
  "lux": 107.0217,
  "hostname": "PixelIt"
}

Sensor

The example below represents a DHT22 installation. Available readings depend on the detected hardware. Unsupported measurements are the string "Not installed"; BME680 read failures can return "Error while reading" instead of a number. Validate types before using values in calculations.

Pressure is in hPa, BME680 gas resistance is in kΩ, humidity and battery level are percentages. Temperature uses the configured Celsius/Fahrenheit unit for DHT22, BME280, BMP280 and BME680. In firmware 2.6.0, the SHT31 path reports Celsius even when Fahrenheit is selected.

HTTP Endpoint [GET]

/api/sensor

MQTT Topic [SUBSCRIBE]

<MasterTopic>/sensor

The response has the following structure:

{
  "humidity": 40,
  "temperature": 21.5,
  "pressure": "Not installed",
  "gas": "Not installed",
  "battery": "Not installed",
  "hostname": "PixelIt"
}

Legacy sensor aliases

Firmware 2.6.0 retains GET /api/dhtsensor as an alias for /api/sensor. It also publishes the same sensor JSON on <MasterTopic>/dhtsensor and, when enabled, <MasterTopic>/<hostname>/dhtsensor. These aliases are for existing integrations; use sensor for new integrations. Despite the old name, their payload is not limited to DHT sensors.

State

The device publishes connected on MQTT connection and configures disconnected as its Last Will. Both use the master-topic state channel.

MQTT Topic [SUBSCRIBE]

<MasterTopic>/state

disconnected (or connected)

Matrix Information

HTTP Endpoint [GET]

/api/matrixinfo

MQTT Topic [PUBLISH]

<MasterTopic>/getMatrixinfo

MQTT Topic [SUBSCRIBE]

<MasterTopic>/matrixinfo

Example response from an ESP8266 (values vary by device):

{
  "pixelitVersion": "2.6.0",
  "note": "",
  "hostname": "PixelIt",
  "deviceID": "example-device",
  "buildSection": "ESP8266_d1_mini",
  "freeSketchSpace": 2695168,
  "wifiRSSI": -58,
  "wifiQuality": 84,
  "wifiSSID": "WiFi",
  "ipAddress": "192.168.0.137",
  "currentMatrixBrightness": 20,
  "freeHeap": 29976,
  "sketchSize": 447424,
  "chipID": 13668362,
  "cpuFreqMHz": 80,
  "sleepMode": false,
  "wifiBSSID": "00:11:22:33:44:55",
  "uptime": 120,
  "resetReason": "Power on",
  "matrixsize": {"cols": 32, "rows": 8}
}

On ESP32, chipID is a string and sketchSize is omitted.

Matrix Config

HTTP Endpoint [GET]

/api/config

MQTT Topic [PUBLISH]

<MasterTopic>/getConfig

MQTT Topic [SUBSCRIBE]

<MasterTopic>/config

The response contains the saved configuration plus showBatteryBtn, which indicates whether the board supports the battery button. The following is an excerpt with example values, not a complete response or a list of defaults:

{
  "matrixBrightnessAutomatic": true,
  "mbaDimMin": 20,
  "mbaDimMax": 255,
  "mbaLuxMin": 0,
  "mbaLuxMax": 250,
  "matrixBrightness": 127,
  "matrixType": 2,
  "note": "",
  "hostname": "PixelIt",
  "matrixTempCorrection": "default",
  "ntpServer": "de.pool.ntp.org",
  "clockTimeZone": 1,
  "clockColor": "#FFFFFF",
  "clockSwitchAktiv": true,
  "clockSwitchSec": 7,
  "clockWithSeconds": false,
  "scrollTextDefaultDelay": 100,
  "bootScreenAktiv": false,
  "mqttAktiv": false,
  "mqttUser": "",
  "mqttPassword": "",
  "mqttServer": "0.0.0.0",
  "mqttMasterTopic": "pixelit/",
  "mqttPort": 1883
}

HTTP Endpoint [POST]

/api/config

MQTT Topic [PUBLISH]

<MasterTopic>/setConfig

Send a JSON object containing the fields you want to change. Omitted fields keep their current values; supplied settings are saved. For example:

{
  "clock24Hours": true,
  "clockAutoFallbackActive": true,
  "clockAutoFallbackTime": 30
}

Additional configuration fields available in 2.6.0:

Fields	Purpose
temperatureUnit	0 for Celsius, 1 for Fahrenheit; see the SHT31 exception under Sensor
clock24Hours, clockDayLightSaving, clockDateDayMonth, clockDayOfWeekFirstMonday	Time format, automatic daylight saving, day/month ordering and first weekday
clockAutoFallbackActive, clockAutoFallbackTime, clockAutoFallbackAnimation	Return to the clock after screen inactivity; timeout is in seconds
clockBlinkAnimated, clockLargeFont, clockFatFont, clockDrawWeekDays	Clock appearance
bootBatteryScreen, bootSound	Battery display and sound at startup
mqttUseDeviceTopic, mqttHAdiscoverable	Per-device MQTT topics and Home Assistant discovery
luxOffset, temperatureOffset, humidityOffset, pressureOffset, gasOffset	Sensor reading corrections
dfpRXpin, dfpTXpin, onewirePin, SCLPin, SDAPin	Peripheral pin selections; use the board-specific values from the WebUI
btn0Pin, btn0PressedLevel, btn0Enabled, btn0Action	Left button configuration; replace 0 with 1 or 2 for the middle or right button
ldrDevice, ldrPulldown, ldrSmoothing	Light sensor selection and configuration
initialVolume	DFPlayer startup volume
sendTelemetry, checkUpdateScreen	Telemetry and update notification options

HTTP configuration writes restart the device after saving. The WebUI also restarts it after configuration changes. MQTT setConfig saves the settings without restarting; restart after changing pins, peripheral selection or connection settings so initialization uses the new configuration.

Button actions are 0 (none), 1 (clock), 2 (toggle sleep), 3 (play/pause), 4 (previous track) or 5 (next track). Use the WebUI to choose valid pins and hardware-dependent settings.

Matrix layout

Set matrixType to match the physical wiring. This selects pixel mapping, not matrix dimensions; released builds remain 32×8.

Value	Layout
1	Column major, top-left origin, zigzag
2	Row major, top-left origin, zigzag
3	Four CJMCU 8×8 tiles, column major, bottom-left origin, progressive
4	MicroMatrix: four 8×8 tiles in one row, top-left origin, row-major zigzag
5	Four CJMCU 8×8 tiles in one row, top-left origin, row-major progressive

Color correction

matrixTempCorrection selects LED color correction or a color-temperature profile. It does not correct environmental temperature readings; use temperatureOffset for those.

• LED correction profiles: default (same as typicalsmd5050), typicalsmd5050, typical8mmpixel.
• Color-temperature profiles: tungsten40w, tungsten100w, halogen, carbonarc, highnoonsun, directsunlight, overcastsky, clearbluesky, warmfluorescent, standardfluorescent, coolwhitefluorescent, fullspectrumfluorescent, growlightfluorescent, blacklightfluorescent, mercuryvapor, sodiumvapor, metalhalide, highpressuresodium.
• Custom RGB correction: a fixed-width string such as "255,200,150". Use three decimal digits for each channel, with commas between channels, and values from 000 to 255.

Use a listed profile or the exact custom format: unrecognized strings enter the custom RGB parser. Restart after changing the correction so LED initialization applies it.

Automatic brightness calibration

matrixBrightnessAutomatic enables automatic adjustment. mbaLuxMin and mbaLuxMax define two measured-light reference points; mbaDimMin and mbaDimMax define the corresponding display brightness values on the 0–255 scale. Use an increasing lux range with distinct endpoints.

For example, this maps 0 lux to brightness 20 and 400 lux to brightness 100:

{"matrixBrightnessAutomatic":true,"mbaLuxMin":0,"mbaLuxMax":400,"mbaDimMin":20,"mbaDimMax":100}

The firmware recalculates brightness approximately once per second using an integer linear mapping. Readings outside the lux reference range are extrapolated; the result is clamped only to 0–255. The configured dim reference points are therefore not hard brightness limits. Manual screen brightness can be overwritten by the next automatic adjustment.

For an analog LDR, ldrDevice accepts GL5516, GL5528, GL5537_1, GL5537_2, GL5539 or GL5549. An unknown name falls back to GL5528. ldrPulldown is the physical pulldown resistance in ohms; ldrSmoothing is passed to the LDR driver's smoothing parameter (firmware initial value 0). These settings apply to the analog LDR, not BH1750 or MAX44009. Restart after changes. See LDR wiring.

Time and clock fallback

ntpServer selects the NTP server. clockTimeZone is a numeric UTC offset in hours, including fractional offsets, rather than a named time zone. For example, 1 selects UTC+1 before daylight saving is applied.

clockDayLightSaving enables the firmware's European-style March-to-October daylight-saving calculation, adding one hour. It is not a worldwide time-zone database. Disable it for regions with different rules and configure the required offset explicitly.

clockAutoFallbackActive returns to the internal clock after clockAutoFallbackTime seconds without a screen message. clockAutoFallbackAnimation selects the transition:

Value	Transition
0	None
1	Fade
2	Colored bar wipe
3	Zigzag wipe
4	Random choice of the three animations

Telemetry and update notifications

sendTelemetry enables uploads to http://pixelit.bastelbunker.de/api/telemetry. Its firmware initial value is true; saved configuration can override it. The first upload is scheduled after approximately 30.3 seconds of uptime, then every 12 hours.

The JSON contains uuid (SHA-1 of the chip ID), version, type, buildSection, a matrix object (type, name, width, height) and a sensors array of detected sensor names. It does not contain the sensor readings. Disable uploads with a configuration write:

{"sendTelemetry":false}

checkUpdateScreen independently enables version checks through http://pixelit.bastelbunker.de/api/lastversion and update notifications on the matrix. Its firmware initial value is also true. Checks start after approximately 30.5 seconds. In 2.6.0, the interval expression evaluates to 48 minutes, despite a source comment saying eight hours.

Every 30 minutes, if the returned version is newer and the display is awake, the firmware sends an update screen with a five-second content lock. As with other forced screens, expiry does not itself restore prior content; a subsequent screen or clock fallback replaces it. This is a notification, not an automatic firmware installation. Disable it with {"checkUpdateScreen":false}. See manual updates.

WiFi Reset

HTTP Endpoint [POST]

/api/wifireset

Erases the WiFi configuration and restarts the device. Device will be in AP mode after restart.

Factory Reset

HTTP Endpoint [POST]

/api/factoryreset

Erases the WiFi configuration and all other settings and restarts the device. Device will be in AP mode after restart.

These reset operations are available over HTTP POST; the firmware does not implement MQTT reset topics.

Sources

These interface details were checked against the 2.6.0 stable release (opens new window), its firmware implementation (opens new window), live-view encoder (opens new window) and daylight-saving calculation (opens new window). Firmware initial values described above apply before saved settings are loaded.