mirror of
https://github.com/nostr-protocol/nips.git
synced 2024-12-12 18:36:24 +00:00
Merge aa8e29902e into a1ca7a194b
This commit is contained in:
Arc
GitHub
commit
86c0cc80c1
162
107.md
Normal file
162
107.md
Normal file
@ -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 <a href="https://github.com/lnbits/arduino-nostr">nostr-arduino</a>
|
||||
|
||||
|
||||
## 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 <a href="https://github.com/lnbits/arduino-nostr">nostr-arduino</a> 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": <String (optional), set a name for the device>,
|
||||
"description": <String (optional), device description>,
|
||||
"categories":[ <String (optional), device category, such as 'boiler'>],
|
||||
"admin_pubkeys": [ [<String (optional), admin user public-key>]],
|
||||
"publish_to_pubkeys":[ [<String (optional), user public-key>]],
|
||||
"intents_from_pubkeys":[ [<String (optional), user public-key>]],
|
||||
"publish_on_change": <Boolean (optional, default `true`), publish event each time a sensor value changes>,
|
||||
"publish_interval": <Integer (optional), publish the sensor value at regular intervals (regardless if the value changes or not). The value is in `millisecods`.>
|
||||
"unix_time": <Integer (optional), set system time in `millisecods`.>
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Description |
|
||||
|---|---|
|
||||
| `admin_pubkeys` | List of public keys that are allowed to configure this device.<br>A fresh/blank device will not have this value.<br/> 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.<br/> 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", <String, pubkey of the configured device]]
|
||||
```
|
||||
- the `d` tag is required, its value MUST be the same as the pubkey of the `device`.
|
||||
|
||||
### Intent Events (`kind: 8000`)
|
||||
---
|
||||
Intent Events represent different actions that can be performed on a device. These actions can be triggered by a `user` or by another `device`.
|
||||
The content of the event is a `JSON` object where for each field:
|
||||
- the key must correspond to the `name` of an entry from the [Data Types](https://github.com/arcbtc/nips/blob/107/107.md#data-events-kind-8001) table
|
||||
- the value represents the value to be set on the device
|
||||
|
||||
**Event Content**:
|
||||
```json
|
||||
{
|
||||
"on": <bool>,
|
||||
"temperature": <float Caelsius>,
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
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", <String, pubkey of the targeted device(s)]]
|
||||
```
|
||||
- the `p` tag is required, its value MUST be the same as the pubkey(s) of the target `device`(s).
|
||||
|
||||
|
||||
### Data Events (`kind: 8001`)
|
||||
---
|
||||
Data Events represent data published by `device`(s).
|
||||
The content of the event is a `JSON` object where for each field:
|
||||
- the key must correspond to the `name` of an entry from the [Data Types](https://github.com/arcbtc/nips/blob/107/107.md#data-events-kind-8001) table
|
||||
- the value represents the data read from a sensor or other type of input
|
||||
|
||||
> [!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": <float Caelsius>,
|
||||
"humidity": <float, percentage>,
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
**Event Tags**:
|
||||
```json
|
||||
"tags": [["p", <String, pubkey of the listening device(s)]]
|
||||
```
|
||||
- the `p` tag is optional. If set then its value MUST be the same as the `publish_to_pubkeys` value from the [Configure Device Event](https://github.com/arcbtc/nips/edit/nip_107/107.md#configure-device-event-kind-30107)
|
||||
|
||||
> [!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 |
|
||||
|
||||
Loading…
Reference in New Issue
Block a user