{"id":13499815,"url":"https://github.com/WebThingsIO/webthing-rust","last_synced_at":"2025-03-29T05:32:24.313Z","repository":{"id":41847072,"uuid":"129794868","full_name":"WebThingsIO/webthing-rust","owner":"WebThingsIO","description":"Rust implementation of a Web Thing server ","archived":false,"fork":false,"pushed_at":"2023-02-18T00:56:50.000Z","size":282,"stargazers_count":209,"open_issues_count":8,"forks_count":25,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-03-24T17:20:27.461Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"Rust","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,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-04-16T19:27:20.000Z","updated_at":"2024-04-15T06:30:34.191Z","dependencies_parsed_at":"2024-04-15T06:30:08.884Z","dependency_job_id":null,"html_url":"https://github.com/WebThingsIO/webthing-rust","commit_stats":{"total_commits":136,"total_committers":15,"mean_commits":9.066666666666666,"dds":"0.18382352941176472","last_synced_commit":"e1a001648de6708e09f923376563ea5fa1b9c3e8"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebThingsIO%2Fwebthing-rust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebThingsIO%2Fwebthing-rust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebThingsIO%2Fwebthing-rust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebThingsIO%2Fwebthing-rust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebThingsIO","download_url":"https://codeload.github.com/WebThingsIO/webthing-rust/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222465660,"owners_count":16989056,"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":["hacktoberfest"],"created_at":"2024-07-31T22:00:43.355Z","updated_at":"2024-10-31T18:31:13.036Z","avatar_url":"https://github.com/WebThingsIO.png","language":"Rust","funding_links":[],"categories":["Section"],"sub_categories":["Libraries"],"readme":"# webthing\n\n[![Build Status](https://github.com/WebThingsIO/webthing-rust/workflows/Rust%20package/badge.svg)](https://github.com/WebThingsIO/webthing-rust/workflows/Rust%20package)\n[![Crates.io](https://img.shields.io/crates/v/webthing.svg)](https://crates.io/crates/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# Using\n\nIf you're using `Cargo`, just add `webthing` to your `Cargo.toml`:\n\n```toml\n[dependencies]\nwebthing = \"0.15\"\n```\n\n## TLS Support\n\nIf you need TLS support for the server, you'll need to compile with the `ssl` feature set.\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-rust/tree/master/examples).\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```rust\nlet mut light = BaseThing::new(\n    \"urn:dev:ops:my-lamp-1234\".to_owned(),\n    \"My Lamp\".to_owned(),\n    Some(vec![\"OnOffSwitch\".to_owned(), \"Light\".to_owned()]),\n    Some(\"A web connected lamp\".to_owned()),\n);\n```\n\nNow we can add the required properties.\n\nThe **`on`** property reports and sets the on/off state of the light. For our purposes, we just want to log the new state if the light is switched on/off.\n\n```rust\nstruct OnValueForwarder;\n\nimpl ValueForwarder for OnValueForwarder {\n    fn set_value(\u0026mut self, value: serde_json::Value) -\u003e Result\u003cserde_json::Value, \u0026'static str\u003e {\n        println!(\"On-State is now {}\", value);\n        Ok(value)\n    }\n}\n\nlet on_description = json!({\n    \"@type\": \"OnProperty\",\n    \"title\": \"On/Off\",\n    \"type\": \"boolean\",\n    \"description\": \"Whether the lamp is turned on\"\n});\nlet on_description = on_description.as_object().unwrap().clone();\nthing.add_property(Box::new(BaseProperty::new(\n    \"on\".to_owned(),\n    json!(true),\n    Some(Box::new(OnValueForwarder)),\n    Some(on_description),\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```rust\nstruct BrightnessValueForwarder;\n\nimpl ValueForwarder for BrightnessValueForwarder {\n    fn set_value(\u0026mut self, value: serde_json::Value) -\u003e Result\u003cserde_json::Value, \u0026'static str\u003e {\n        println!(\"Brightness is now {}\", value);\n        Ok(value)\n    }\n}\n\nlet brightness_description = json!({\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});\nlet brightness_description = brightness_description.as_object().unwrap().clone();\nthing.add_property(Box::new(BaseProperty::new(\n    \"brightness\".to_owned(),\n    json!(50),\n    Some(Box::new(BrightnessValueForwarder)),\n    Some(brightness_description),\n)));\n```\n\nNow we can add our newly created thing to the server and start it:\n\n```rust\nlet mut things: Vec\u003cArc\u003cRwLock\u003cBox\u003cdyn Thing + 'static\u003e\u003e\u003e\u003e = Vec::new();\nthings.push(Arc::new(RwLock::new(Box::new(light)));\n\n// If adding more than one thing, use ThingsType::Multiple() with a name.\n// In the single thing case, the thing's name will be broadcast.\nlet mut server = WebThingServer::new(\n    ThingsType::Multiple(things, \"LightAndTempDevice\".to_owned()),\n    Some(8888),\n    None,\n    None,\n    Box::new(Generator),\n    None,\n    None,\n);\nlet server_addr = server.create();\nserver.start();\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```rust\nlet mut thing = BaseThing::new(\n    \"urn:dev:ops:my-humidity-sensor-1234\".to_owned(),\n    \"My Humidity Sensor\".to_owned(),\n    Some(vec![\"MultiLevelSensor\".to_owned()]),\n    Some(\"A web connected humidity sensor\".to_owned()),\n);\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    ```rust\n    let level_description = json!({\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    let level_description = level_description.as_object().unwrap().clone();\n    thing.add_property(Box::new(BaseProperty::new(\n        \"level\".to_owned(),\n        json!(0),\n        None,\n        Some(level_description),\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```rust\nlet sensor = Arc::new(RwLock::new(Box::new(sensor))));\nlet cloned = sensor.clone();\nthread::spawn(move || {\n    let mut rng = rand::thread_rng();\n\n    // Mimic an actual sensor updating its reading every couple seconds.\n    loop {\n        thread::sleep(time::Duration::from_millis(3000));\n        let t = cloned.clone();\n        let new_value = json!(\n            70.0 * rng.gen_range::\u003cf32\u003e(0.0, 1.0) * (-0.5 + rng.gen_range::\u003cf32\u003e(0.0, 1.0))\n        );\n\n        {\n            let mut t = t.write().unwrap();\n            let prop = t.find_property(\"level\".to_owned()).unwrap();\n            let _ = prop.set_value(new_value.clone());\n        }\n\n        t.write()\n            .unwrap()\n            .property_notify(\"level\".to_owned(), new_value);\n    }\n});\n```\n\nThis will update our property with random sensor readings. The new property value is then sent to 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWebThingsIO%2Fwebthing-rust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FWebThingsIO%2Fwebthing-rust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWebThingsIO%2Fwebthing-rust/lists"}