nips/107.md

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. A user can publish these event kinds:

Kind		Description	NIP
30107	config	Configure a device	NIP-107 Configure Device Event
8000	intent	Trigger an action on a device	NIP-107 Intent Event
`8001.	data	Publish the state of a device	NIP-91 Event Kinds

The content of events can be transmitted in clear text (for public data) or as NIP-59 Gift Wrap.

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:

{
    "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. 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:

  "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 array representing the data type and the data value as specified in NIP-91 Event Kinds

Event Content:

 [[<Integer, between 8001 and 8999>, <Any Type> ]]

Example that turns on a device and sets the temperature to 20.9 degrees Celsius:

[[8001, true], [8003, 20.9]]

Event Tags:

  "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 kind of the event and the content must follow ths specification from NIP-91 Event Kinds.

Note

If a device has more sensors attached (eg: temperature and humidity) then it will publish separate events for each measured value.

Event Tags:

  "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

Important

If the transmission mode is encrypted (NIP-59 Gift Wrap) 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