{"id":13499807,"url":"https://github.com/WebThingsIO/webthing-node","last_synced_at":"2025-03-29T05:32:22.847Z","repository":{"id":46434794,"uuid":"124952941","full_name":"WebThingsIO/webthing-node","owner":"WebThingsIO","description":"Node.js implementation of a Web Thing server","archived":false,"fork":false,"pushed_at":"2022-12-10T16:14:15.000Z","size":523,"stargazers_count":232,"open_issues_count":14,"forks_count":46,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-03-23T05:31:56.641Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WebThingsIO.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-12T21:19:33.000Z","updated_at":"2024-08-12T19:36:54.000Z","dependencies_parsed_at":"2023-01-26T08:46:39.752Z","dependency_job_id":null,"html_url":"https://github.com/WebThingsIO/webthing-node","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebThingsIO%2Fwebthing-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebThingsIO%2Fwebthing-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebThingsIO%2Fwebthing-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebThingsIO%2Fwebthing-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebThingsIO","download_url":"https://codeload.github.com/WebThingsIO/webthing-node/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246145012,"owners_count":20730494,"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":"2024-07-31T22:00:43.139Z","updated_at":"2025-03-29T05:32:22.492Z","avatar_url":"https://github.com/WebThingsIO.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Section"],"sub_categories":["Libraries"],"readme":"# webthing\n\n[![Build Status](https://github.com/WebThingsIO/webthing-node/workflows/Node.js%20package/badge.svg)](https://github.com/WebThingsIO/webthing-node/workflows/Node.js%20package)\n[![NPM](https://img.shields.io/npm/v/webthing.svg)](https://www.npmjs.com/package/webthing)\n[![license](https://img.shields.io/badge/license-MPL--2.0-blue.svg)](LICENSE)\n\nImplementation of an HTTP [Web Thing](https://iot.mozilla.org/wot/).\n\n# Installation\n\n`webthing` can be installed via `npm`, as such:\n\n```shell\n$ npm install webthing\n```\n\n# Example\n\nIn this example we will set up a dimmable light and a humidity sensor (both using fake data, of course). Both working examples can be found in [here](https://github.com/WebThingsIO/webthing-node/tree/master/example).\n\n## Dimmable Light\n\nImagine you have a dimmable light that you want to expose via the web of things API. The light can be turned on/off and the brightness can be set from 0% to 100%. Besides the name, description, and type, a [`Light`](https://iot.mozilla.org/schemas/#Light) is required to expose two properties:\n* `on`: the state of the light, whether it is turned on or off\n    * Setting this property via a `PUT {\"on\": true/false}` call to the REST API toggles the light.\n* `brightness`: the brightness level of the light from 0-100%\n    * Setting this property via a PUT call to the REST API sets the brightness level of this light.\n\nFirst we create a new Thing:\n\n```javascript\nconst light = new Thing('urn:dev:ops:my-lamp-1234',\n                        'My Lamp',\n                        ['OnOffSwitch', 'Light'],\n                        'A web connected lamp');\n```\n\nNow we can add the required properties.\n\nThe **`on`** property reports and sets the on/off state of the light. For this, we need to have a `Value` object which holds the actual state and also a method to turn the light on/off. For our purposes, we just want to log the new state if the light is switched on/off.\n\n```javascript\nlight.addProperty(\n  new Property(\n    light,\n    'on',\n    new Value(true, (v) =\u003e console.log('On-State is now', v)),\n    {\n      '@type': 'OnOffProperty',\n      title: 'On/Off',\n      type: 'boolean',\n      description: 'Whether the lamp is turned on',\n    }));\n```\n\nThe **`brightness`** property reports the brightness level of the light and sets the level. Like before, instead of actually setting the level of a light, we just log the level.\n\n```javascript\nlight.addProperty(\n  new Property(\n    light,\n    'brightness',\n    new Value(50, v =\u003e console.log('Brightness is now', v)),\n    {\n      '@type': 'BrightnessProperty',\n      title: 'Brightness',\n      type: 'number',\n      description: 'The level of light from 0-100',\n      minimum: 0,\n      maximum: 100,\n      unit: 'percent',\n    }));\n```\n\nNow we can add our newly created thing to the server and start it:\n\n```javascript\n// If adding more than one thing, use MultipleThings() with a name.\n// In the single thing case, the thing's name will be broadcast.\nconst server = new WebThingServer(SingleThing(light), 8888);\n\nprocess.on('SIGINT', () =\u003e {\n  server.stop().then(() =\u003e process.exit()).catch(() =\u003e process.exit());\n});\n\nserver.start().catch(console.error);\n```\n\nThis will start the server, making the light available via the WoT REST API and announcing it as a discoverable resource on your local network via mDNS.\n\n## Sensor\n\nLet's now also connect a humidity sensor to the server we set up for our light.\n\nA [`MultiLevelSensor`](https://iot.mozilla.org/schemas/#MultiLevelSensor) (a sensor that returns a level instead of just on/off) has one required property (besides the name, type, and optional description): **`level`**. We want to monitor this property and get notified if the value changes.\n\nFirst we create a new Thing:\n\n```javascript\nconst sensor = new Thing('urn:dev:ops:my-humidity-sensor-1234',\n                         'My Humidity Sensor',\n                         ['MultiLevelSensor'],\n                         'A web connected humidity sensor');\n```\n\nThen we create and add the appropriate property:\n* `level`: tells us what the sensor is actually reading\n    * Contrary to the light, the value cannot be set via an API call, as it wouldn't make much sense, to SET what a sensor is reading. Therefore, we are creating a *readOnly* property.\n\n    ```javascript\n    const level = new Value(0.0);\n\n    sensor.addProperty(\n      new Property(\n        sensor,\n        'level',\n        level,\n        {\n          '@type': 'LevelProperty',\n          title: 'Humidity',\n          type: 'number',\n          description: 'The current humidity in %',\n          minimum: 0,\n          maximum: 100,\n          unit: 'percent',\n          readOnly: true,\n        }));\n    ```\n\nNow we have a sensor that constantly reports 0%. To make it usable, we need a thread or some kind of input when the sensor has a new reading available. For this purpose we start a thread that queries the physical sensor every few seconds. For our purposes, it just calls a fake method.\n\n```javascript\n// Poll the sensor reading every 3 seconds\nsetInterval(() =\u003e {\n  // Update the underlying value, which in turn notifies all listeners\n  level.notifyOfExternalUpdate(readFromGPIO());\n}, 3000);\n```\n\nThis will update our `Value` object with the sensor readings via the `this.level.notifyOfExternalUpdate(readFromGPIO());` call. The `Value` object now notifies the property and the thing that the value has changed, which in turn notifies all websocket listeners.\n\n# Adding to Gateway\n\nTo add your web thing to the WebThings Gateway, install the \"Web Thing\" add-on and follow the instructions [here](https://github.com/WebThingsIO/thing-url-adapter#readme).\n\n# Resources\n\n* https://iot.mozilla.org/things/\n* https://hacks.mozilla.org/2018/05/creating-web-things-with-python-node-js-and-java/\n* https://nodejs.org/en/\n* https://github.com/rzr/webthing-iotjs/wiki\n* https://youtu.be/Z-oiFl6gwGw\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWebThingsIO%2Fwebthing-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FWebThingsIO%2Fwebthing-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWebThingsIO%2Fwebthing-node/lists"}