A ready-to-use webserver for the WS2801-Pi package.
npm install ws2801-webserverThis 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.
The wiring of the Pi is described here.
There are basically two ways to use WS2801-webserver:
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
1. Create a new npm project folder
2. Install this module: npm i ws2801-webserver
``typescript
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();
`
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
#### 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.
Starts the webserver.
Stops the webserver.
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
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.
Returns wheter the auth mechanism is enabled or not.
- Route: /login-required
- Method: Get
- Returns:
- 200
- Type: {loginRequired: boolean}
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
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
Returns the current state of the led strip.
- Route: /led-strip
- Method: Get
- Returns:
- 200
- Type: {ledStrip: LedStrip}
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
Clears the led strip.
- Route: /led-strip/clear
- Method: Post
- Returns:
- 200
- Type: {ledStrip: LedStrip}
- 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
- 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
- Route: /led-strip/brightness
- Method: Get
- Returns: {brightness: number}
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
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
Cancels the currently running animation.
- Route /led-strip/set
- Method: Delete
- Returns:
- 200
- The animation was stopped successfully
- Type: string
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
Triggered every time the LedStrip is changed.
- Event: 'led-strip__changed'
- Payload: LedStrip
Triggered ecery time the brightness gets changed.
- Event: 'brightness__changed'
- Payload: number
Triggered ecery time an animation was started.
- Event: 'animation__started'
Triggered ecery time an animation was finished.
- Event: 'animation__finished'
Triggered ecery time an animation was stopped.
- Event: 'animation__stopped'
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`.