nips/107.md

86 lines
3.6 KiB
Markdown
Raw Normal View History

2023-10-10 17:27:08 -04:00
NIP-107
======
Nostr Internet of Things
-----------------------------------
`draft` `optional` `author:benarc` `author:blackcoffeebtc`
2023-10-19 05:55:59 -04:00
## Rationale
2023-10-10 17:27:08 -04:00
2023-10-19 06:00:51 -04:00
The terms/conditions of IoT software/hardware is horrible. A user should be able to message a light or heating and ask it to turn on/off. Nostr gives the simple, permissionless development environment IoT needs.
2023-10-10 17:27:08 -04:00
All communication happens over [NIP04](https://github.com/nostr-protocol/nips/blob/master/04.md).
## Terms
2023-10-19 06:00:51 -04:00
- `user` - user operating IoT devices with NOSTR key-pair and a client made specifically for IoT
2023-10-10 17:27:08 -04:00
- `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
2023-10-19 06:27:29 -04:00
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`.
2023-10-19 05:53:43 -04:00
The `device` can also push data such as sensor readings and updates.
2023-10-10 17:27:08 -04:00
2023-10-19 06:27:29 -04:00
## Events
2023-10-10 17:27:08 -04:00
2023-10-19 05:53:55 -04:00
A `device` or a `user` can publish these event kinds:
2023-10-10 17:27:08 -04:00
| Kind | | Description | NIP |
|---------|------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------|
2023-10-19 06:27:29 -04:00
| `4 ` | `direct_message` | Communicate between two `devices` or between a `device` and a `user`.<br/>The messages must be a JSON following the structures defined In this NIP. | [NIP04](https://github.com/nostr-protocol/nips/blob/master/04.md) |
2023-10-10 17:27:08 -04:00
2023-10-19 06:27:29 -04:00
### Messages
JSON messages that represent different actions or states can be exchanged between two or more `devices` or between `users` and `devices`.
Each `JSON` message `MUST` have a `type` field indicating the what the JSON represents. Possible types:
2023-10-10 17:27:08 -04:00
2023-10-19 06:27:29 -04:00
| Message Type | Sent By | Description |
|--------------|----------------|------------------|
| 0 | User | Configure Device |
| 1 | User \| Device | Command |
| 2 | Device | State Data |
### Event: Configure `device`
2023-10-24 02:29:59 -04:00
This message is sent by a `user` to a `device`. The `device` saves the config locally and uses it.
2023-10-10 17:27:08 -04:00
**Event Content**:
```json
{
2023-10-24 02:29:59 -04:00
"type": 0,
"admin_pubkeys": [ [<String (optional), admin user public-key>]],
"name": <String (optional), set a name for the device>,
2023-10-10 17:27:08 -04:00
"description": <String (optional), device description>,
"categories":[ <String (optional), device category, such as 'boiler'>],
2023-10-24 02:29:59 -04:00
"send_to_pubkeys":[ [<String (optional), user public-key>]],
"commands_from_pubkeys":[ [<String (optional), user public-key>]],
2023-10-10 17:27:08 -04:00
}
```
Note:
2023-10-24 02:29:59 -04:00
- `admin_pubkeys`:
- list of public keys that are allowed to configure this device. A fresh/blank device will not have this value, so the first received `"type: 0"` should set it.
2023-10-10 17:27:08 -04:00
- `users`:
2023-10-24 02:29:59 -04:00
- a list that can restrict access to public-keys, `device`(s) also has keys and can be a `user`.
2023-10-10 17:27:08 -04:00
### Event: Update a `device`
**Event Content**:
```json
{
2023-10-19 05:54:38 -04:00
"id": <String, UUID generated by the user. Sequential IDs (`0`, `1`, `2`...) are discouraged>,
2023-10-10 17:27:08 -04:00
"device_id": <String, UUID of the stall to which this device belong to>,
"settings":[ [<String (optional), user public-key>]]
}
```
Note:
- `settings`:
2023-10-19 06:00:51 -04:00
- Standard `settings` include:
2023-10-10 17:27:08 -04:00
- eg: `[["on", <bool>], ["range", <int, 0-1000>], ["timer_on", <int unix timestamp>], ["timer_off", <int unix timestamp>]]`