README

WS2801-webserver

This is a ready-to-use webserver for the WS2801-Pi package.

There is also a TypeScript client for this webserver.

You may also want to take a look at WS2801 which includes the Webserver (this package), the Alexa handler, and the LedController.

Wiring

The wiring of the Pi is described here.

Usage

There are basically two ways to use WS2801-webserver:

Using this repository

Clone this repository
Edit the config file as described here
Run the build script: npm run build
Run the start script: npm start

Using the npm module

Create a new npm project folder
Install this module: npm i ws2801-webserver

import {Config as WebserverConfig, Ws2801Webserver} from 'ws2801-webserver';

const config: WebserverConfig = {
  port: 45451,
  confirmationPort: 45452,
  amountOfLeds: 10,
  useAuth: true,
};

const webserver: Ws2801Webserver = new Ws2801Webserver(config);

webserver.start();

Configuration

The config can be specified when initializing the Ws2801Webserver. If no config was specified or if the repository is used, the defaultConfig which is stored here.

The config can look like this:

{
  port: 45451,
  confirmationPort: 45452,
  amountOfLeds: 10,
  useAuth: true,
};

port is used for the webserver that provides the most routes. This may be publicly accessible.
confirmationPort is only needed if the auth mechanism is enabled (useAuth is set to true). This webserver provides the confirmation routes for new registrations. This should never be publicly accessible, at least until a proper confirmation website is available.
amountOfLeds is used to specify how many leds are connected to the Pi. This is only necessary if no other ledController is specified in the constructor.
useAuth is used to define whether the auth mechanism should be used or not.

Functions

constructor

Parameters:

config
- optional
- Type: Config
- The config for this module, as described here. If no value is set, the default config is used.
ledController
- optional
- Type: LedController
- The led controller that controls the leds of the connected led strip. If no value is specified, WS2801-webserver will create its own LedController with the LedAmount that is configured in the default config.
  - To avoid rendering problems, there should be only one LedController instance.

start

Starts the webserver.

stop

Stops the webserver.

getExpressServer

Returns the express server instance used by WS2801-webserver. This can be used to add more routes.

Returns

Returns the express server instance.

Type: express

Routes

The routes marked with [Auth] can only be used if the auth mechanism is enabled. If the auth mechanism is enabled, an apiKey must be provided as a query parameter for all routes except /login-required and /register. Otherwise a 403 is returned.

GET: /login-required

Returns wheter the auth mechanism is enabled or not.

Route: /login-required
Method: Get
Returns:
- 200
  - Type: {loginRequired: boolean}

Post: /register [Auth]

Registers a new user and waits for confirmation.

Route: /register
Method: Post
Body: {name: string, apiKey: string}
Returns:
- 200
  - Registration was successful
    - Type: {apiKey: string}
- 400
  - Body was incorrect
    - Type: string
- 403
  - Username already exists
    - Type: string
  - Registration was not confirmed
    - Type: string
  - Registration was not successful
    - Type: string

Post: /login [Auth]

Checks if the specified apiKey is working.

Route: /login
Method: Post
Returns:
- 200
  - Login was successful
    - Type: {apiKey: string}
- 400
  - Body was incorrect
    - Type: string
- 403
  - User in not registered
    - Type: string
  - User is not allowed to use the api
    - Type: string

Get: /led-strip

Returns the current state of the led strip.

Route: /led-strip
Method: Get
Returns:
- 200
  - Type: {ledStrip: LedStrip}

Post: /led-strip/fill

Fills the led strip with a single color.

Route /led-strip/fill
Method: Post
Body:
- color
  - Type: LedColor
- brightness
  - optional
  - Type: number
Returns:
- 200
  - The Led Strip was changed successfully.
    - Type: {ledStrip: LedStrip}
- 400
  - Body was incorrect
    - Type: string

Post: /led-strip/clear

Clears the led strip.

Route: /led-strip/clear
Method: Post
Returns:
- 200
  - Type: {ledStrip: LedStrip}

Post: /led-strip/led/:ledIndex/set

Route: /led-strip/led/:ledIndex/set
Method: Post
Route Parameter:
- ledIndex: number
Body:
- color
  - Type: LedColor
- brightness (brightness is set for the whole LED strip)
  - optional
  - Type: number
Returns:
- 200
  - The Led was successfully changed.
    - Type: {ledStrip: LedStrip}
- 400
  - Body was incorrect
    - Type: string

Post: /led-strip/brightness/set

Route: /led-strip/brightness/set
Method: Post
Body:
- brightness (brightness is set for the whole LED strip)
  - Type: number
Returns:
- 200
  - The brightness successfully changed.
    - Type: string
- 400
  - Body was incorrect
    - Type: string

Get: /led-strip/brightness

Route: /led-strip/brightness
Method: Get
Returns: {brightness: number}

Post: /led-strip/set

Sets all leds according to the provided colors.

Route /led-strip/set
Method: Post
Body:
- ledStrip
  - Type: LedStrip
- brightness
  - optional
  - Type: number
Returns:
- 200
  - The Led Strip was changed successfully.
    - Type: {ledStrip: LedStrip}
- 400
  - Body was incorrect
    - Type: string
  - Provided LedStrip was invalid
    - Type: string

Post: /led-strip/animation/start

Executes the provided animation script. The animation script must be passed as a string. The animation script can access the LED controller via ledController and the amount of Leds via ledAmount.

Route /led-strip/set
Method: Post
Body:
- animationScript
  - Type: string
Returns:
- 200
  - The animation was started successfully
    - Type: string
- 400
  - Body was incorrect
    - Type: string

Delete: /led-strip/animation/stop

Cancels the currently running animation.

Route /led-strip/set
Method: Delete
Returns:
- 200
  - The animation was stopped successfully
    - Type: string

Get: /led-strip/animation/finished

Returns as soon as the currently running animation finished.

Route /led-strip/animation/finished
Method: Get
Returns:
- 200
  - The animation was successfully finished.
    - Type: string

Socket.Io Events

LedStrip changed

Triggered every time the LedStrip is changed.

Event: 'led-strip__changed'
Payload: LedStrip

Brightness changed

Triggered ecery time the brightness gets changed.

Event: 'brightness__changed'
Payload: number

Animation started

Triggered ecery time an animation was started.

Event: 'animation__started'

Animation finished

Triggered ecery time an animation was finished.

Event: 'animation__finished'

Animation stopped

Triggered ecery time an animation was stopped.

Event: 'animation__stopped'

Authorization

The auth mechanism provides simple authorization. It can be enabled or disabled via the config. To check if a WS2801-webserver instance uses authorization, the loginRequired route can be used.

The authorization works as follows:

New user requests registration using the register route, providing a username and an apiKey
If the username does not already exist, a confirmation link gets logged in the console.
Once the confirmation link is clicked, the user is registered.
The user can then use the login route to verify that he is logged in.
The api key must then be provided as a query parameter for all other api calls, otherwise a 403 error will be returned.

The user data is stored in $(PWD)/.storage/webserver-api-keys.json.

Usage no npm install needed!