{"id":24983943,"url":"https://github.com/steffenkn/ws2801-webserver","last_synced_at":"2025-03-29T10:15:18.230Z","repository":{"id":57400070,"uuid":"325065780","full_name":"SteffenKn/WS2801-webserver","owner":"SteffenKn","description":"A ready-to-use webserver for the WS2801-Pi package.","archived":false,"fork":false,"pushed_at":"2021-06-07T18:01:11.000Z","size":91,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2024-04-23T21:39:22.540Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SteffenKn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-12-28T16:50:11.000Z","updated_at":"2021-06-07T18:01:14.000Z","dependencies_parsed_at":"2022-09-19T01:00:24.036Z","dependency_job_id":null,"html_url":"https://github.com/SteffenKn/WS2801-webserver","commit_stats":null,"previous_names":["steffenkn/ws2801-pi-webserver"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SteffenKn%2FWS2801-webserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SteffenKn%2FWS2801-webserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SteffenKn%2FWS2801-webserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SteffenKn%2FWS2801-webserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SteffenKn","download_url":"https://codeload.github.com/SteffenKn/WS2801-webserver/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246168108,"owners_count":20734390,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-04T09:40:51.406Z","updated_at":"2025-03-29T10:15:18.211Z","avatar_url":"https://github.com/SteffenKn.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WS2801-webserver\n\nThis is a ready-to-use webserver for the [WS2801-Pi package](https://www.npmjs.com/package/ws2801-pi).\n\nThere is also a [TypeScript client](https://www.npmjs.com/package/ws2801-client) for this webserver.\n\nYou may also want to take a look at [WS2801](https://github.com/SteffenKn/WS2801) which includes the [Webserver](https://www.npmjs.com/package/ws2801-webserver) (this package), the [Alexa handler](https://www.npmjs.com/package/ws2801-alexa), and the [LedController](https://www.npmjs.com/package/ws2801-pi).\n\n## Wiring\n\nThe wiring of the Pi is described [here](https://github.com/SteffenKn/WS2801-PI#wiring).\n\n## Usage\n\nThere are basically two ways to use WS2801-webserver:\n\n### Using this repository\n\n1. Clone this repository\n2. Edit the config file as described [here](#Configuration)\n3. Run the build script: `npm run build`\n4. Run the start script: `npm start`\n\n### Using the npm module\n\n1. Create a new npm project folder\n2. Install this module: `npm i ws2801-webserver`\n\n```typescript\nimport {Config as WebserverConfig, Ws2801Webserver} from 'ws2801-webserver';\n\nconst config: WebserverConfig = {\n  port: 45451,\n  confirmationPort: 45452,\n  amountOfLeds: 10,\n  useAuth: true,\n};\n\nconst webserver: Ws2801Webserver = new Ws2801Webserver(config);\n\nwebserver.start();\n```\n\n## Configuration\n\nThe config can be specified when initializing the Ws2801Webserver.\nIf no config was specified or if the repository is used, the defaultConfig which is stored [here](./src/config/config.ts).\n\nThe config can look like this:\n```\n{\n  port: 45451,\n  confirmationPort: 45452,\n  amountOfLeds: 10,\n  useAuth: true,\n};\n```\n\n- `port` is used for the webserver that provides the most routes. This may be publicly accessible.\n- `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.\n- `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.\n- `useAuth` is used to define whether the auth mechanism should be used or not.\n## Functions\n\n### constructor\n\n#### Parameters:\n\n- `config`\n  - optional\n  - Type: [Config](./src/types/config.ts)\n  - The config for this module, as described [here](#Configuration). If no value is set, the [default config](./src/config/config.ts) is used.\n\n- `ledController`\n  - optional\n  - Type: [LedController](https://github.com/SteffenKn/WS2801-PI/blob/develop/src/index.ts#L44)\n  - 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](./src/config/config.ts).\n    - To avoid rendering problems, there should be only one LedController instance.\n\n### start\n\nStarts the webserver.\n\n### stop\n\nStops the webserver.\n\n### getExpressServer\n\nReturns the express server instance used by WS2801-webserver. This can be used to add more routes.\n\n#### Returns\n\nReturns the express server instance.\n- Type: [express](https://www.npmjs.com/package/express)\n\n## Routes\n\nThe routes marked with [Auth] can only be used if the auth mechanism is enabled.\nIf 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.\n\n### GET: /login-required\n\nReturns wheter the auth mechanism is enabled or not.\n\n- Route: /login-required\n- Method: Get\n- Returns:\n  - 200\n    - Type: {loginRequired: boolean}\n\n### Post: /register [Auth]\n\nRegisters a new user and waits for confirmation.\n\n- Route: /register\n- Method: Post\n- Body: {name: string, apiKey: string}\n- Returns:\n  - 200\n    - Registration was successful\n      - Type: {apiKey: string}\n  - 400\n    - Body was incorrect\n      - Type: string\n  - 403\n    - Username already exists\n      - Type: string\n    - Registration was not confirmed\n      - Type: string\n    - Registration was not successful\n      - Type: string\n### Post: /login [Auth]\n\nChecks if the specified apiKey is working.\n\n- Route: /login\n- Method: Post\n- Returns:\n  - 200\n    - Login was successful\n      - Type: {apiKey: string}\n  - 400\n    - Body was incorrect\n      - Type: string\n  - 403\n    - User in not registered\n      - Type: string\n    - User is not allowed to use the api\n      - Type: string\n\n### Get: /led-strip\n\nReturns the current state of the led strip.\n\n- Route: /led-strip\n- Method: Get\n- Returns:\n  - 200\n    - Type: {ledStrip: [LedStrip](https://github.com/SteffenKn/WS2801-PI/blob/develop/src/index.ts#L6)}\n\n### Post: /led-strip/fill\n\nFills the led strip with a single color.\n\n- Route /led-strip/fill\n- Method: Post\n- Body:\n  - color\n    - Type: [LedColor](https://github.com/SteffenKn/WS2801-PI/blob/develop/src/index.ts#L8-L12)\n  - brightness\n    - optional\n    - Type: number\n- Returns:\n  - 200\n    - The Led Strip was changed successfully.\n      - Type: {ledStrip: [LedStrip](https://github.com/SteffenKn/WS2801-PI/blob/develop/src/index.ts#L6)}\n  - 400\n    - Body was incorrect\n      - Type: string\n\n### Post: /led-strip/clear\n\nClears the led strip.\n\n- Route: /led-strip/clear\n- Method: Post\n- Returns:\n  - 200\n    - Type: {ledStrip: [LedStrip](https://github.com/SteffenKn/WS2801-PI/blob/develop/src/index.ts#L6)}\n\n### Post: /led-strip/led/:ledIndex/set\n\n- Route: /led-strip/led/:ledIndex/set\n- Method: Post\n- Route Parameter:\n  - ledIndex: number\n- Body:\n  - color\n    - Type: [LedColor](https://github.com/SteffenKn/WS2801-PI/blob/develop/src/index.ts#L8-L12)\n  - brightness (brightness is set for the whole LED strip)\n    - optional\n    - Type: number\n- Returns:\n  - 200\n    - The Led was successfully changed.\n      - Type: {ledStrip: [LedStrip](https://github.com/SteffenKn/WS2801-PI/blob/develop/src/index.ts#L6)}\n  - 400\n    - Body was incorrect\n      - Type: string\n\n### Post: /led-strip/brightness/set\n\n- Route: /led-strip/brightness/set\n- Method: Post\n- Body:\n  - brightness (brightness is set for the whole LED strip)\n    - Type: number\n- Returns:\n  - 200\n    - The brightness successfully changed.\n      - Type: string\n  - 400\n    - Body was incorrect\n      - Type: string\n\n### Get: /led-strip/brightness\n\n- Route: /led-strip/brightness\n- Method: Get\n - Returns: {brightness: number}\n\n### Post: /led-strip/set\n\nSets all leds according to the provided colors.\n\n- Route /led-strip/set\n- Method: Post\n- Body:\n  - ledStrip\n    - Type: [LedStrip](https://github.com/SteffenKn/WS2801-PI/blob/develop/src/index.ts#L6)\n  - brightness\n    - optional\n    - Type: number\n- Returns:\n  - 200\n    - The Led Strip was changed successfully.\n      - Type: {ledStrip: [LedStrip](https://github.com/SteffenKn/WS2801-PI/blob/develop/src/index.ts#L6)}\n  - 400\n    - Body was incorrect\n      - Type: string\n    - Provided LedStrip was invalid\n      - Type: string\n\n### Post: /led-strip/animation/start\n\nExecutes the provided animation script. The animation script must be passed as a string.\nThe animation script can access the [LED controller](https://github.com/SteffenKn/WS2801-PI/blob/develop/src/index.ts#L44) via `ledController` and the amount of Leds via `ledAmount`.\n\n- Route /led-strip/set\n- Method: Post\n- Body:\n  - animationScript\n    - Type: string\n- Returns:\n  - 200\n    - The animation was started successfully\n      - Type: string\n  - 400\n    - Body was incorrect\n      - Type: string\n\n### Delete: /led-strip/animation/stop\n\nCancels the currently running animation.\n\n- Route /led-strip/set\n- Method: Delete\n- Returns:\n  - 200\n    - The animation was stopped successfully\n      - Type: string\n\n### Get: /led-strip/animation/finished\n\nReturns as soon as the currently running animation finished.\n\n- Route /led-strip/animation/finished\n- Method: Get\n- Returns:\n  - 200\n    - The animation was successfully finished.\n      - Type: string\n\n\n## Socket.Io Events\n\n### LedStrip changed\n\nTriggered every time the LedStrip is changed.\n\n- Event: 'led-strip__changed'\n- Payload: [LedStrip](https://github.com/SteffenKn/WS2801-PI/blob/develop/src/index.ts#L6)\n\n### Brightness changed\n\nTriggered ecery time the brightness gets changed.\n\n- Event: 'brightness__changed'\n- Payload: number\n\n### Animation started\n\nTriggered ecery time an animation was started.\n\n- Event: 'animation__started'\n\n### Animation finished\n\nTriggered ecery time an animation was finished.\n\n- Event: 'animation__finished'\n\n### Animation stopped\n\nTriggered ecery time an animation was stopped.\n\n- Event: 'animation__stopped'\n\n## Authorization\n\nThe auth mechanism provides simple authorization. It can be enabled or disabled via the config.\nTo check if a WS2801-webserver instance uses authorization, the [loginRequired route](#get-login-required) can be used.\n\nThe authorization works as follows:\n\n- New user requests registration using the [register route](#post-register-auth), providing a username and an apiKey\n- If the username does not already exist, a confirmation link gets logged in the console.\n- Once the confirmation link is clicked, the user is registered.\n- The user can then use the [login route](#post-login-auth) to verify that he is logged in.\n- The api key must then be provided as a query parameter for all other api calls, otherwise a 403 error will be returned.\n\nThe user data is stored in `$(PWD)/.storage/webserver-api-keys.json`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteffenkn%2Fws2801-webserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteffenkn%2Fws2801-webserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteffenkn%2Fws2801-webserver/lists"}