diff --git a/107.md b/107.md new file mode 100644 index 00000000..02a6572a --- /dev/null +++ b/107.md @@ -0,0 +1,162 @@ +NIP-107 +====== + +Nostr Internet of Things +----------------------------------- + +`draft` `optional` `author:benarc` `author:blackcoffeebtc` `author:motorina0` + +## Rationale + +The terms/conditions of IoT software/hardware is horrible. A user should be able to message a light or heating system and ask it to turn on/off. Nostr gives the simple, permissionless development environment IoT needs. + + +## Terms + +- `user` - user operating IoT devices with NOSTR key-pair and a client made specifically for IoT +- `device` - device to operate over Nostr with NOSTR key-pair, using a microcontroller client like nostr-arduino + + +## Nostr IoT Clients + +### User + +Where the `user` registers 'device'(s) and its keys, then updates the `device`(s). + +### Device + +The `device` uses a client like nostr-arduino to receive commands from the `user` or another `device`. +The `device` can also push data such as sensor readings and updates. + +## Events + +A `device` can publish any of the events described in [Data Types](https://github.com/arcbtc/nips/blob/107/107.md#data-types). +A `user` can publish these event kinds: + +| Kind | | Description | NIP | +|---------|----------|-------------------------------|-----------------------------------------------------------------------------------------| +| `30107` | `config` | Configure a device | [NIP-107 Configure Device Event](https://github.com/arcbtc/nips/edit/nip_107/107.md#configure-device-event) | +| `8000` | `intent` | Trigger an action on a device | [NIP-107 Intent Event](https://github.com/arcbtc/nips/blob/107/107.md#intent-events-kind-8000) | +| `8001` | `data` | Publish the state of a `device` | [NIP-107 Data Event](https://github.com/arcbtc/nips/blob/107/107.md#data-events-kind-8001) | + + +The content of events can be transmitted in clear text (for public data) or as [NIP-59 Gift Wrap](https://github.com/staab/nips/blob/NIP-59/59.md). + + +### Configure Device Event (`kind: 30107`) +--- +This message is sent by an admin `user` to a `device`. The `device` saves the config locally and then uses it. + +**Event Content**: +```json +{ + "name": , + "description": , + "categories":[ ], + "admin_pubkeys": [ []], + "publish_to_pubkeys":[ []], + "intents_from_pubkeys":[ []], + "publish_on_change": , + "publish_interval": + "unix_time": +} +``` + +| Field | Description | +|---|---| +| `admin_pubkeys` | List of public keys that are allowed to configure this device.
A fresh/blank device will not have this value.
The `admin_pubkeys` implicitly have the `actions_from_pubkeys` permissions. | +| `publish_to_pubkeys` | List of public keys to which events are published. | +| `actions_from_pubkeys` | List of public keys that are allowed to trigger an action on this device.
The `admin_pubkeys` implicitly have the `actions_from_pubkeys` permissions. | + + +> [!IMPORTANT] +> The content of the `30107` event should be encrypted if the user chooses the "encrypted" mode + +**Event Tags**: +```json + "tags": [["d", , + "temperature": , + ... +} +``` + +Example that turns on a device and sets the temperature to `20.9` degrees Celsius: +```json +{ + "on": true, + "temperature": 20.9 +} +``` + + +**Event Tags**: +```json + "tags": [["p", [!NOTE] +> If a device has more sensors attached (eg: temperature and humidity) then it cam publish one unified event for all measured values. + +**Event Content**: +```json +{ + "temperature": , + "humidity": , + ... +} +``` + +**Event Tags**: +```json + "tags": [["p", [!IMPORTANT] +> If the transmission mode is encrypted ([NIP-59 Gift Wrap](https://github.com/staab/nips/blob/NIP-59/59.md)) then an individual message must be published for each public key in `publish_to_pubkeys`. +> +> +## Data Types + +Below is a non exhaustive list of data types that may be used in the content of the event. + + +| name | type | unit | example | description | +| ----------------- | ------- | --------------- | -------------------- | --------------------------------------------------------------- | +| temperature | float | celsius | 20.9 | Measures the ambient temperature | +| pressure | float | pascals | 1013 | Measures the atmospheric pressure | +| location | array | decimal degrees | [51.5053, -0.08737] | Specifies coordinates in latitude and longitude | +| light | float | lux | 500 | Measures the intensity of light | +| humidity | float | percentage | 45.5 | Measures the moisture level in the air | +| rain | boolean | millimeters | true | Detects if it's raining | +| moisture | float | percentage | 32.2 | Measures the moisture content in materials | +| air_quality | float | AQI | 75 | Measures the overall quality of the air based on pollutants | +| gas_concentration | float | ppm | 400 | Measures the concentration of a specific gas in the air | +| uv_index | float | index | 5.5 | Measures the strength of sunburn-producing ultraviolet radiation | +| wind_speed | float | m/s | 10.2 | Measures the speed of wind | +| wind_direction | float | degrees | 30 | Indicates the direction from which the wind is coming | +| sound_intensity | float | decibels | 65.5 | Measures the loudness or amplitude of sound | +