# API

You can use the API via the HTTP REST Interface or MQTT. The HTTP API is available at /api/ and the MQTT API at <MasterTopic>/. You can use both APIs at the same time.

TIP

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

# Interfaces

# REST

The port is 80, The REST API is available at /api/. The following endpoints are available:

# MQTT

The default MasterTopic is pixelit/, but can be changed in the WebUI. The MasterTopic is used as a prefix for all MQTT topics. If enabled, the device also uses an additional topic with the name <MasterTopic>/<hostname>. When you use MQTT, you are able to use multiple PixelIts but with the additional topic you can also address a single PixelIt.

With MQTT enabled, the device will also discoverable via Home Assistant (opens new window).

TIP

We recommend using MQTT.

# Endpoints

The following endpoints are available:

Endpoint Description Details
screen Show screen on device Details
brightness Get or set brightness 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

Most important endpoint is /api/screen or <MasterTopic>/setScreen. This endpoint is used to display a single screen on Pixelit. The following elements are supported:

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": {
    "show": true,
    "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
scrollText Boolean / String true / false / auto Required Big front
scrollTextDelay Integer 1 - 9999 Required (when scrollText is used)
centerText Boolean true / false Required
position JSON {"x":8, "y":1} Required
color JSON {"r":255, "g":255, "b":255}, Required (or hexColor)
hexColor String #FFFFFF since v0.3.2 Alternatively to color

# Sleep Mode


sleepMode could be send as a key of a screen payload. When sleepMode is active, the device dimms down the matrix to brightness: 0. Additionally while sleepMode is active the /api/screen-endpoint and <MasterTopic>/setScreeen-topic are not fully evaluated. Only when sleepMode previously or within the same message-body is set to false , the requested screen will be displayed.

Disclaimer

Enabeling sleepMode does not enable power saving features on the MCU itself, like e.g. deep sleep functionality of an ESP8266.

{
  "sleepMode": false
}
Parameter Type Values Description
sleepMode Boolean true / false When acitve sleepMode disables the rendering of new screens

# Brightness


{
  "brightness": 125
}
Parameter Type Values Description
brightness Integer 0 - 255 Sets the brightness

# Switch Animation


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

# Call bitmapWipe example

{
  "switchAnimation": {
    "aktiv": true,
    "animation": "fade",
    "data": [0, 0, 0, 0, 0, 0],
    "width": 8
  }
}
Parameter Type Values Description
aktiv Boolean true / false
animation String fade / coloredBarWipe / zigzagWipe / bitmapWipe / random bitmapWipe call example
data Integer Array [0, 0, 0, 0, 0, 0] Required for bitmapWipe
width Integer 1 - 32 Required for bitmapWipe height always needs to be 8

# Clock


{
  "clock": {
    "show": true,
    "switchAktiv": true,
    "withSeconds": true,
    "switchSec": 5,
    "drawWeekDays": true,
    "color": {
      "r": 255,
      "g": 255,
      "b": 255
    },
    "hexColor": "#FFFFFF"
  }
}
Parameter Type Values Description
show Boolean true / false Required
switchAktiv Boolean true / false Switch clock/date
switchSec Integer 1 - 9999 Required (when Switch clock/date is used) Switch clock/date in seconds
drawWeekDays Boolean true / false since v1.1.0 Draw weekdays
color JSON {"r":255, "g":255, "b":255}, Color of Clock (or hexColor)
hexColor String #FFFFFF since v0.3.2 Alternatively to color

# Bitmap


{
  "bitmap": {
    "data": [0, 0, 0, 0, 0, 0],
    "position": {
      "x": 0,
      "y": 0
    },
    "size": {
      "width": 8,
      "height": 8
    }
  }
}
Parameter Type Values Description
data Integer Array [0, 0, 0, 0, 0, 0] Required
position JSON {"x":0, "y":0} Required
size JSON {"width":8, "height":8} Required

# Bitmaps


How to display multiple bitmaps on one screen.

Limitations

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

{
  "bitmaps": [
    {
      "data": [0, 0, 0, 0, 0, 0],
      "position": {
        "x": 0,
        "y": 0
      },
      "size": {
        "width": 8,
        "height": 8
      }
    },
    {
      "data": [0, 0, 0, 0, 0, 0],
      "position": {
        "x": 8,
        "y": 0
      },
      "size": {
        "width": 8,
        "height": 8
      }
    },
    {
      "data": [0, 0, 0, 0, 0, 0],
      "position": {
        "x": 16,
        "y": 0
      },
      "size": {
        "width": 8,
        "height": 8
      }
    },
    {
      "data": [0, 0, 0, 0, 0, 0],
      "position": {
        "x": 24,
        "y": 0
      },
      "size": {
        "width": 8,
        "height": 8
      }
    }
  ]
}
Parameter Type Values Description
data Integer Array [0, 0, 0, 0, 0, 0] Required
position JSON {"x":0, "y":0} Required
size JSON {"width":8, "height":8} Required

# Bitmap Animation


{
  "bitmapAnimation": {
    "data": [
      [0, 0, 0, 0, 0, 0],
      [0, 0, 0, 0, 0, 0],
      [0, 0, 0, 0, 0, 0]
    ],
    "animationDelay": 20,
    "rubberbanding": false,
    "limitLoops": 0
  }
}
Parameter Type Values Description
data Array of Integer Arrays [[0, 0, 0, 0, 0, 0],[0, 0, 0, 0, 0, 0]] Required Only 8x8 BMPs are supported here!
animationDelay Integer 0 - 99999 Required Higher is a slower animation
rubberbanding Boolean true / false Should the animation run back and forth
limitLoops Integer 0-99 Limiting the loops
position JSON {"x":0, "y":0} Postion

# 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":10} Required
color JSON {"r":255, "g":255, "b":255}, Color of Clock (or hexColor)
hexColor String #FFFFFF since v0.3.2 Alternatively 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":10} Required
color JSON {"r":255, "g":255, "b":255}, Color of Clock (or hexColor)
hexColor String #FFFFFF since v0.3.2 Alternatively to color

# Set GPIO

{
  "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 1 - 99999999 Automatic fall back to false in milliseconds

# Sound


# Option 1

This option allows the use of multiple folders, but has the limitations, that the controls next and previous are omitted.

The following folders structure must be provided: sd:\01\001.mp3

{
  "sound": {
    "volume": 20,
    "control": "play",
    "folder": 1,
    "file": 1
  }
}
Parameter Type Values Description
volume Integer 0 - 30 Required
control String play / pause Required
folder Integer 1 - 99 Required
file Integer 1 - 255 Required

# Option 2

This option also enables the controls next and previous, but the following order structure must be provided: sd:\MP3\0001.mp3

{
  "sound": {
    "volume": 20,
    "control": "play",
    "file": 1
  }
}
Parameter Type Values Description
volume Integer 0 - 30 Required
control String play / pause / next / previous Required
file Integer 1 - 3000 Required

# Brightness

HTTP Endpoint [GET]

/api/brightness

This option can be used to query the current brightness. If u use MQTT, use <MasterTopic>/matrixinfo to get the current brightness.

The response has the following structure:

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

# Buttons

HTTP Endpoint [GET]

/api/buttons

The HTTP response has the following structure:

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

MQTT Topic [SUBSCRIBE]

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

The MQTT response has the following structure:

{
    "true/false"
}

# 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
}

# Sensor

HTTP Endpoint [GET]

/api/sensor

MQTT Topic [SUBSCRIBE]

<MasterTopic>/sensor

The response has the following structure:

{
  "humidity": 40,
  "temperature": 21.5
}

# State

Its possible to get a disconnection (and connection) message via the MQTT LWT (Last Will and Testament) Feature.

MQTT Topic [SUBSCRIBE]

<MasterTopic>/state

disconnected (or connected)

# Matrix Infomation

HTTP Endpoint [GET]

/api/matrixinfo

MQTT Topic [PUBLISH]

<MasterTopic>/getMatrixinfo

MQTT Topic [SUBSCRIBE]

<MasterTopic>/matrixinfo

The response has the following structure:

{
  "pixelitVersion": "0.3.4",
  "note": "",
  "hostname": "PixelIt",
  "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
}

# Matrix Config

HTTP Endpoint [GET]

/api/config

MQTT Topic [PUBLISH]

<MasterTopic>/getConfig

MQTT Topic [SUBSCRIBE]

<MasterTopic>/config

The response has the following structure:

{
  "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

To set the configuration, the upper structure must be followed.

# WiFi Reset

HTTP Endpoint [GET]

/api/wifireset

MQTT Topic [PUBLISH]

<MasterTopic>/wifiReset

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

# Factory Reset

HTTP Endpoint [GET]

/api/factoryreset

MQTT Topic [PUBLISH]

<MasterTopic>/factoryReset

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