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

1. Clone this repository
2. Edit the config file as described here
3. Run the build script: npm run build
4. Run the start script: npm start

Using the npm module

1. Create a new npm project folder
2. 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.