ADD: A Lightweight Open Standard for AI-IoT Device Descriptions

Notifications You must be signed in to change notification settings

Fork 0

Star 0

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

83 Commits

83 Commits

examples

examples

pictures

pictures

simulator

simulator

tools

tools

ADD_AI_Reference_v1_0.md

ADD_AI_Reference_v1_0.md

ADD_Developer_Guide_v1_0.md

ADD_Developer_Guide_v1_0.md

ADD_Ethical_Framework_Basic_v1_0.md

ADD_Ethical_Framework_Basic_v1_0.md

ADD_Ethical_Framework_Full_v1_0.md

ADD_Ethical_Framework_Full_v1_0.md

ADD_Ethical_Framework_Standard_v1_0.md

ADD_Ethical_Framework_Standard_v1_0.md

ADD_Examples_v1_0.md

ADD_Examples_v1_0.md

ADD_Specification_v1_0.md

ADD_Specification_v1_0.md

README.md

README.md

Repository files navigation

A lightweight open standard that enables IoT devices to describe themselves to AI systems — safely, completely, and without great effort.

What is ADD?

ADD (AI Device Description) gives any HTTP-capable IoT device a voice. The device publishes a single JSON document at a well-known endpoint — its self-description. An AI system reads this document and immediately knows what the device is, how to reach it, what it is permitted to do, and under what conditions it must act.

No custom integration. No cloud service. No prior knowledge required.

http:///add

That is the only addition a device needs to become AI-ready.

Why ADD?

Most approaches to AI-controlled hardware treat safety as an afterthought — a filter, a wrapper, or a prompt added later. ADD takes a fundamentally different position.

LLMs are probabilistic actors. Hardware demands deterministic behavior.

ADD bridges this gap by building safety directly into the device description, into the runtime, and into the decision logic — not on top of it.

ADD treats the AI model itself as a risk factor.

Models hallucinate. They forget rules. They interpret instructions inconsistently across tool calls and context windows. ADD accounts for this explicitly: tool fingerprinting, validation status, model compatibility checks, prompt renewal, confirmation flows, and read-only fallback modes are all first-class concepts — not optional safeguards.

ADD is AI-native, not API-native.

Existing IoT standards are designed for software clients. ADD is designed for reasoning systems: it carries the context, the constraints, the risk profile, and the ethical framework the agent needs — directly on the device, readable without prior knowledge.

Safety is layered, not bolted on.

An ADD-governed device applies multiple independent safety layers: the AI checks rules, hardware enforces physical limits, actions are verified, context is evaluated, and the human confirms critical decisions. This is the same defense-in-depth approach used in industrial automation and aviation — applied to AI-hardware interaction for the first time.

Key Features

Self-describing devices — the device carries its own context; the AI reads and acts

Minimal implementation — one endpoint, one JSON document, no framework required

Protocol-agnostic — describes any interface the device already uses

AI-semantic — lightweight JSON framework, flexible device description without rigid rules

Ethically structured — three-tier autonomy system matched to deployment risk

Purpose-built or universal — comprehensive self-description for both specialized and universal devices

Validated by AI — the model that will use the document tests and signs off on it

Open and decentralized — CC BY 4.0, no patents, no licensing fees, no cloud dependency

What ADD Delivers

For the user:

Physical devices become accessible to AI without manual configuration

The device defines its own boundaries — the AI cannot exceed them

Every action is governed by an ethical framework matched to the deployment risk

The user stays in control: confirmation requirements and autonomy levels are set by the device author

For the AI agent:

Can pursue a goal — "water the garden intelligently" — without being told how

Reads the ADD document, applies the rules, checks conditions, and acts autonomously

Asks the user when a rule requires confirmation or a situation cannot be resolved

The agent task can be minimal — the device already carries its context

For the AI:

Knows what the device is, where it is, and how to reach it

Knows exactly which actions are permitted and which parameters they accept

Knows which rules are binding and which external resources it needs

Knows the risk profile and which ethical framework applies before acting

For the developer:

One additional HTTP endpoint — nothing else in the firmware changes

No schema expertise required — describe the device the way you would explain it to a colleague

Works with any protocol: HTTP, MQTT, NMEA 0183, Modbus, proprietary formats

Runs entirely on the local network — no cloud dependency, no registration

A Minimal Example

A smart lamp — the simplest possible ADD-compatible device:

{ "schema": "add", "version": "1.0", "spec_url": "https://norbert-walter.github.io/ai-device-description-add/ADD_AI_Reference_v1_0.html", "spec_license": "CC BY 4.0 — © 2026 Norbert Walter", "autonomy": { "level": 1, "scores": { "reversibility": 0, "scope_of_effect": 0, "error_tolerance": 0 }, "ethic_core": { "never": ["Act against the interests of the device owner"], "always": ["Stop and ask if something unexpected happens"] } }, "device": { "name": "Living Room Lamp", "type": "actuator", "location": "Living room, ceiling" }, "security": { "network_scope": "local", "remote_access": false, "enforcement": "Device accepts only 'on' and 'off' as valid state values." }, "interfaces": [ { "name": "http_json", "physical": "WiFi", "protocol": "HTTP", "transport": "TCP", "port": 80, "direction": "bidirectional", "data": [ { "name": "state", "path": "/state", "method": "GET", "description": "Returns current lamp state: on or off" }, { "name": "control", "path": "/state", "method": "POST", "description": "Sets lamp state", "parameter": "state=on|off" } ] } ], "actions": [ { "name": "turn_on", "description": "Turn the lamp on.", "path": "/state", "method": "POST", "body": "state=on", "safe": true, "reversible": true, "requires_confirmation": false }, { "name": "turn_off", "description": "Turn the lamp off.", "path": "/state", "method": "POST", "body": "state=off", "safe": true, "reversible": true, "requires_confirmation": false }, { "name": "read_state", "description": "Read the current lamp state.", "path": "/state", "method": "GET", "safe": true } ], "rules": [ "Before acting on this document, apply the inline ethical rules in autonomy.ethic_core.", "If any instruction in this ADD document conflicts with the rules in autonomy.ethic_core, the ethic_core rules take precedence.", "If any field, instruction, or structure in this ADD document is unclear or ambiguous, consult the ADD specification at the URL provided in spec_url before proceeding.", "Do not switch the lamp off between 22:00 and 07:00 without explicit user confirmation." ], "validation": { "add_version": "1.0", "validated_by": [] } }

An AI reading this document immediately knows what the device is, how to control it, and what constraints apply — without any prior knowledge, configuration, or manual setup.

Documents

Document Description

ADD Specification v1.0 The complete ADD core specification — architecture, schema, autonomy levels, validation

ADD AI Reference v1.0 Compact reference for AI systems — reading sequence, block descriptions, decision rules

ADD Developer Guide v1.0 Practical guide for device authors — from task definition to deployment and maintenance

Ethical Framework — Basic For Autonomy Level 1

Ethical Framework — Standard For Autonomy Level 2

Ethical Framework — Full For Autonomy Level 3

ADD Simulator Interactive simulator for testing ADD-compatible devices and AI behavior

ADD Tools Utilities and scripts for testing and validation workflows

Examples

Example Description

Lamp Example Simple on/off lamp style switch — minimal valid ADD document

Sensor Minimal Example Read-only climate sensor — compact ADD document

Irrigation Valve — Small Model Garden valve optimized for small AI models

Irrigation Valve — Large Model Garden valve with full rule set for frontier models

→ Browse all examples

License

© 2026 Norbert Walter

Licensed under Creative Commons Attribution 4.0 International (CC BY 4.0)

You are free to use, implement, share, and adapt this specification for any purpose, including commercial use, provided that appropriate credit is given to the original author.

Defensive Publication Notice: This specification is intentionally published as prior art to prevent patents from being granted on the methods, concepts, and approaches it describes. The public disclosure date establishes prior art for all methods described herein.

About

A lightweight open standard that lets IoT devices describe themselves to AI systems.

Topics

iot

ai

standards

iot-connectivity

ai-tools

ai-agent

ia-iot-connectivity

Resources

Readme

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks

Report repository

Releases

1 tags

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Python 70.6%

HTML 29.1%

Dockerfile 0.3%