Skip to content

Latest commit

 

History

History
526 lines (421 loc) · 10.8 KB

API.md

File metadata and controls

526 lines (421 loc) · 10.8 KB

API

EvLamp provides a simple API based on HTTP GET and POST requests containing JSON data.

Contents

Get firmware information

Request

GET /api/info

Response

{
  "app_name": <String, Application name, usually "EvLamp">,
  "app_version": <String, Application version>,
  "build_date": <String, Application build date>,
  "idf_ver": <String, Version of used ESP-IDF>
}

Example

{
  "app_name": "EvLamp",
  "app_version": "0.6.3",
  "build_date": "May  2 2022",
  "idf_ver": "v5.0-dev-1829-ge29e96101d-dirty"
}

Get current WiFi settings

Request

GET /api/settings/wifi

Response

{
  "mode": <Integer, WiFi mode. 1 - Station, 2 - Access point>,
  "ip": {
    /* IP settings for both AP and station modes */
    "dhcp": <Boolean, DHCP client enable in station mode>,
    "ip": <String, IP address. In station mode only makes sense if DHCP client is disabled>,
    "netmask": <String, Network mask. In station mode only makes sense if DHCP client is disabled>,
    "gateway": <String, Gateway IP address. In station mode only makes sense if DHCP client is disabled>,
    "dns": <String, IP-address of DNS server. In station mode only makes sense if DHCP client is disabled, 
          in AP mode used as fallback DNS server'>
  },
  "ap": {
    /* Access Point settings, only makes sense in AP mode */
    "ssid": <String, SSID of Access Point>,
    "channel": <Integer, Channel number>,
    "password": <String, Access Point WPA2 password. If empty, Access point will be in open mode>,
  },
  "sta": {
    /* Station settings, only makes sense in station mode */
    "ssid": <String, Contains the SSID of the network being connected to in station mode>,
    "password": <String, WPA2 password>,
  }
}

Example

{
  "mode": 1,
  "ip": {
    "dhcp": true,
    "ip": "192.168.1.1",
    "netmask": "255.255.255.0",
    "gateway": "192.168.1.1",
    "dns": "192.168.1.1"
  },
  "ap": {
    "ssid": "EvLamp",
    "channel": 6,
    "password": ""
  },
  "sta": {
    "ssid": "MyHomeWiFi",
    "password": "SuperSecret"
  }
}

Set WiFi settings

Request

POST /api/settings/wifi

{
  "mode": <Integer, WiFi mode. 1 - Station, 2 - Access point>,
  "ip": {
    /* IP settings for both AP and station modes */
    "dhcp": <Boolean, DHCP client enable in station mode>,
    "ip": <String, IP address. In station mode only makes sense if DHCP client is disabled>,
    "netmask": <String, Network mask. In station mode only makes sense if DHCP client is disabled>,
    "gateway": <String, Gateway IP address. In station mode only makes sense if DHCP client is disabled>,
    "dns": <String, IP-address of DNS server. In station mode only makes sense if DHCP client is disabled, 
          in AP mode used as fallback DNS server'>
  },
  "ap": {
    /* Access Point settings, only makes sense in AP mode */
    "ssid": <String, SSID of Access Point>,
    "channel": <Integer, Channel number>,
    "password": <String, Access Point WPA2 password. If empty, Access point will be in open mode>,
  },
  "sta": {
    /* Station settings, only makes sense in station mode */
    "ssid": <String, Contains the SSID of the network being connected to in station mode>,
    "password": <String, WPA2 password>,
  }
}

Response

{
  "result": <Integer, Result code. 0 - no errors>,
  "name": <String, Name of the result code, "ESP_OK" for result code 0>,
  "message": <String, Error message if result code != 0>
}

Get current LED settings

Request

GET /api/settings/leds

Response

{
  "block_width": <Integer, single block (LED matrix) width (number of columns), 8..128>,
  "block_height": <Integer, single block (LED matrix) height (number of rows), 8..128>,
  "h_blocks": <Integer, number of blocks horizontally>,
  "v_blocks": <Integer, number of blocks vertically>,
  "type": <Integer, Type of LEDs. 0 - WS2812, 1 - SK6812, 2 - APA106, 3 - SM16703>,
  "current_limit": <Integer, Approximate limit of current consumed by all LEDs in milliamps.
                   The larger this value, the higher the maximum brightness.>,
}

Note: The total number of blocks (h_blocks * v_blocks) should not be more than 8

Example

Single 16x16 WS2812B matrix:

{
  "block_width": 16,
  "block_height": 16,
  "h_blocks": 1,
  "v_blocks": 1,
  "type": 0,
  "current_limit": 5000
}

Set LED settings

Request

POST /api/settings/leds

{
  "block_width": <Integer, single block (LED matrix) width (number of columns), 8..128>,
  "block_height": <Integer, single block (LED matrix) height (number of rows), 8..128>,
  "h_blocks": <Integer, number of blocks horizontally>,
  "v_blocks": <Integer, number of blocks vertically>,
  "type": <Integer, Type of LEDs. 0 - WS2812, 1 - SK6812, 2 - APA106, 3 - SM16703>,
  "current_limit": <Integer, Approximate limit of current consumed by all LEDs in milliamps.
                   The larger this value, the higher the maximum brightness.>,
}

Response

{
  "result": <Integer, Result code. 0 - no errors>,
  "name": <String, Name of the result code, "ESP_OK" for result code 0>,
  "message": <String, Error message if result code != 0>
}

Reset system settings

Resets all system settings including both WiFi and LED settings to default values. After resetting device must be rebooted.

Request

GET /api/settings/reset

Response

{
  "result": <Integer, Result code. 0 - no errors>,
  "name": <String, Name of the result code, "ESP_OK" for result code 0>,
  "message": <String, Error message if result code != 0>
}

Reboot device

Request

GET /api/reboot

Response

No response, device just reboots.

Get current lamp state

Request

GET /api/lamp/state

Response

{
  "on": <Boolean, true - Lamp is on, false - Lamp is off>,
  "effect": <Integer, Current effect ID, 0-based>,
  "brightness": <Integer, LED matrix brightness, 0..255>,
  "fps": <Integer, Frames per seconds, 0..120>
}

Set lamp state

With this function you can switch LEDs on and off, change current effect, brightness and FPS.

Request

POST /api/lamp/state

{
  "on": <Boolean, true - Lamp is on, false - Lamp is off>,
  "effect": <Integer, Selected effect ID, 0-based>,
  "brightness": <Integer, LED matrix brightness, 0..255>,
  "fps": <Integer, Frames per seconds, 0..120>
}

Any item in request can be omitted. For example, you can switch off the lamp with this POST:

{ "on": false }

or change effect to "Fire" (id = 1) and set brightness:

{ "effect": 1, "brightness": 50 }

Response

{
  "result": <Integer, Result code. 0 - no errors>,
  "name": <String, Name of the result code, "ESP_OK" for result code 0>,
  "message": <String, Error message if result code != 0>
}

Get full list of effects and its parameters

Request

GET /api/effects

Response

[
  {
    "name": <String, Effect name>,
    "params": [
      {
        "name": <String, Parameter name>,
        "min": <Integer, Minimal value>,
        "max": <Integer, Maximal value>,
        "default": <Integer, Default value>,
        "value": <Integer, Current value>
      },
      ...
    ]
  },
  ...
]

The effect index in the response array is the effect ID. The parameter's index in the effect's parameter list is the parameter ID.

Example

[{
    "name": "Color lamp",
    "params": [{
        "name": "Red",
        "min": 0,
        "max": 255,
        "default": 255,
        "value": 255
      }, {
        "name": "Green",
        "min": 0,
        "max": 255,
        "default": 159,
        "value": 159
      }, {
        "name": "Blue",
        "min": 0,
        "max": 255,
        "default": 70,
        "value": 70
      }]
  },
  {
    "name": "Fire",
    "params": [{
        "name": "Palette",
        "min": 0,
        "max": 7,
        "default": 0,
        "value": 0
      }, {
        "name": "Scale",
        "min": 10,
        "max": 100,
        "default": 60,
        "value": 60
      }]
  },
  ... 
  {
    "name": "Fireflies",
    "params": [{
        "name": "Number of fireflies",
        "min": 4,
        "max": 48,
        "default": 16,
        "value": 16
      }, {
        "name": "Chaotic movements",
        "min": 0,
        "max": 1,
        "default": 1,
        "value": 1
      }, {
        "name": "Speed",
        "min": 1,
        "max": 255,
        "default": 255,
        "value": 255
      }, {
        "name": "Update time",
        "min": 1,
        "max": 10,
        "default": 3,
        "value": 3
      }]
  }]

Reset parameters of all effects

Request

GET /api/effects/reset

Response

{
  "result": <Integer, Result code. 0 - no errors>,
  "name": <String, Name of the result code, "ESP_OK" for result code 0>,
  "message": <String, Error message if result code != 0>
}

Get current effect parameters

Request

GET /api/lamp/effect

Response

{
  "effect": <Integer, Current effect ID, 0-based>,
  "params": [
    {
      "name": <String, Parameter name>,
      "min": <Integer, Minimal value>,
      "max": <Integer, Maximal value>,
      "default": <Integer, Default value>,
      "value": <Integer, Current value>
    },
    ...
  ]
}

Example

{
  "effect": 1,
  "params": [
    {
      "name": "Palette",
      "min": 0,
      "max": 7,
      "default": 0,
      "value": 0
    },
    {
      "name": "Scale",
      "min": 10,
      "max": 100,
      "default": 60,
      "value": 60
    }
  ]
}

Set effect parameters

Request

POST /api/lamp/effect

{
  "effect": <Integer, Effect ID, 0-based>,
  "params": [
    <Integer, 0 parameter value>,
    ...
    <Integer, n parameter value>,
  ]
}

Example

Set Palette = 1 and Scale = 60 for the "Fire" effect.

{
  "effect": 1,
  "params": [ 1, 60 ]
}

Response

{
  "result": <Integer, Result code. 0 - no errors>,
  "name": <String, Name of the result code, "ESP_OK" for result code 0>,
  "message": <String, Error message if result code != 0>
}