LIT Web Server

Summary

Provides a RESTful interface and webpage to access the features of the LIT daemon.

Requires

LIT Daemon

Setup

Configuration

Configuration is done through environment variables. If LIT_USER and LIT_PASSWORD are defined, basic authentication will be required. This should be run with gunicorn

Installation

1. Install pip3 if you haven't already $ sudo apt-get install pip3
2. Install lit-web $ sudo pip3 install --system lit-web
3. If you did not already have lit-core installed, set it up https://github.com/lit-illumination-technology/lit_core#installation
4. Install the start script $ cd /etc/system/systemd && sudo wget https://raw.githubusercontent.com/lit-illumination-technology/lit_web_server/master/litwebserver.service
5. Change your username and password Edit the LIT_USERNAME and LIT_PASSWORD variables $ sudo nano /etc/systemd/system/litwebserver.service
6. Start and enable the script $ sudo systemctl start litwebserver && sudo systemctl enable litwebserver

API Requests

All endpoints are prefixed with /api/v1/

Method	Endpoint	Request	Response
GET	effects		{"effects": [{"name": string, "default_speed": number, "schema": schema},]}
POST	effects/{effect_name}	{"args": args, "parameters": parameters}	{"code": int, "message": string, "transaction_id": int}
DELETE	effects	{"effect_id": int} | {"transaction_id": int}	{"code": int, "message": string}
POST	presets/{preset_name}	{"parameters": parameters}	{"code": int, "message": string, "transaction_id": int}
POST	history	{"back": bool?, "forward": bool?}	{"code": int, "message": string}
GET	colors		{"colors": [{"name": string, "rgb": [number, number, number]},]}
GET	ranges		{"sections": [string,], "zones": ["string"]}

schema:

{
  arg_name: {
    "required": boolean,
    "value": {
      "type": color|number
    }
  }
}

color:

{
  "default": [number, number, number],
  "type": "color"
}

number:

{
  "default": number,
  "min": number,
  "max": number,
  "type": "number"
}

args:

{arg_name_1: arg_value_1, arg_name_2: arg_value_2, ...}

parameters:

{"overlayed": boolean?, "opacity": number?, "ranges": [string]?, speed: number?}

FAQ

How do I access the webpage?

Get the ip address of your raspberry pi (ip addr), then in a web browser navigate to that ip address followed by a colon, folowed by the port number specified in the config. If you use port 80, then the colon and port are not required.

The IP address of my Raspberry Pi keeps changing. How do I tell it to stop?

Like this or this

How do I connect from outside the network

To control your lights from anywhere, you will need to setup port forwarding on your router. The steps are specific to the router firmware, but you will need to forward the port specified in the config to the ip address of your raspberry pi.

How do I authenticate with the api?

Authentication is done with http basic authentication. In the request header, set the Authorization cookie to Basic XXX where XXX is username:password in base 64.

Is this secure?

No. Not at all. If you don't want random internet people intercepting your password and turning on your lights in the middle of the night, you will need to setup https.

Suggested Integrations

• Tasker is an android app that allows you to automate tasks. Events can trigger a POST request that turn on/off the lights. Leaving your home wifi can turn the lights off. Your phone's morning alarm can turn the lights on. To set this up the Tasker action is Net -> Http POST and the settings are:
  • Server:Port: username:password@url
    • ex: nick:[email protected]
  • Path: command/effect
  • Data/File: {"name": "effect", "args": {...}}
    • ex: {"name": "on". "args": {"color": [255, 0, 255]}}
  • Content Type: application/json
  • Trust Any Certificate: ✓
• Turn off the lights when you turn off or put your computer to sleep. This one is more operating system dependent, but for many linux systems this would involve a systemd service with WantedBy=sleep.target and a curl request.