Merge aa8e29902e into a1ca7a194b

Added example data types table

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 <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                      |
+

29.md

@@ -30,8 +30,6 @@ When encountering just the `<host>` without the `'<group-id>`, clients MAY infer
 
 Events sent by users to groups (chat messages, text notes, moderation events etc) MUST have an `h` tag with the value set to the group _id_.
 
-`h` tags MAY include the group's name as the second argument. This allows `unmanaged` groups to be assigned human-readable names without relay support.
-
 ## Timeline references
 
 In order to not be used out of context, events sent to these groups may contain references to previous events seen from the same relay in the `previous` tag. The choice of which previous events to pick belongs to the clients. The references are to be made using the first 8 characters (4 bytes) of any event in the last 50 events seen by the user in the relay, excluding events by themselves. There can be any number of references (including zero), but it's recommended that clients include at least 3 and that relays enforce this.
@@ -242,3 +240,5 @@ A definition for `kind:10009` was included in [NIP-51](51.md) that allows client
 ### Using `unmanaged` relays
 
 To prevent event leakage, when using `unmanaged` relays, clients should include the [NIP-70](70.md) `-` tag, as just the `previous` tag won't be checked by other `unmanaged` relays.
+
+Groups MAY be named without relay support by adding a `name` to the corresponding tag in a user's `kind 10009` group list.

51.md

@@ -29,7 +29,7 @@ For example, _mute list_ can contain the public keys of spammers and bad actors
 | Public chats      | 10005 | [NIP-28](28.md) chat channels the user is in                | `"e"` (kind:40 channel definitions)                                               |
 | Blocked relays    | 10006 | relays clients should never connect to                      | `"relay"` (relay URLs)                                                            |
 | Search relays     | 10007 | relays clients should use when performing search queries    | `"relay"` (relay URLs)                                                            |
-| Simple groups     | 10009 | [NIP-29](29.md) groups the user is in                       | `"group"` ([NIP-29](29.md) group id + relay URL), `"r"` for each relay in use     |
+| Simple groups     | 10009 | [NIP-29](29.md) groups the user is in                       | `"group"` ([NIP-29](29.md) group id + relay URL + optional group name), `"r"` for each relay in use     |
 | Interests         | 10015 | topics a user may be interested in and pointers             | `"t"` (hashtags) and `"a"` (kind:30015 interest set)                              |
 | Emojis            | 10030 | user preferred emojis and pointers to emoji sets            | `"emoji"` (see [NIP-30](30.md)) and `"a"` (kind:30030 emoji set)                  |
 | DM relays         | 10050 | Where to receive [NIP-17](17.md) direct messages            | `"relay"` (see [NIP-17](17.md))                                                   |