Core Concepts

Use this page when SDK APIs feel abstract. The goal is to give you a compact mental model you can carry into every guide.

Why this matters

Once you understand node -> element -> model, you can usually predict where an operation belongs before looking at the API reference.

The five concepts that unlock the SDK

Term	What it is	Why you care
Node	One physical mesh device	This is what you discover, provision, and manage
Element	A functional part inside a node	Lets one device expose multiple independently-addressable roles
Model	A behavior attached to an element	This is where on/off, dimming, sensors, and vendor features live
Provisioning	The secure join process	Turns an untrusted device into part of your network
Publish / Subscribe	How messages move through the mesh	Lets one sender target one device, one room, or many devices

Mental model in one diagram

Physical device (Node)
└─ Elements
  ├─ Element 0
  │  ├─ Generic OnOff model
  │  └─ Light Lightness model
  ├─ Element 1
  │  └─ Sensor model
  └─ Element 2
    └─ Vendor model

Most SDK calls follow that hierarchy: find node -> pick model -> send or read state.

Node: the device identity in your network

A node is a physical mesh device, such as a light, switch, sensor, or gateway-attached target.

You provision nodes, assign keys to nodes, and target node elements and models.

const node = mesh.configuredNodes?.[0];

At this point, you should think of a node as the outer container, not the behavior surface.

Element: independently addressable function blocks

An element is a functional block inside a node. One physical device can expose multiple elements.

Use different elements when different parts of the same hardware need separate addresses or model sets.

Model: behavior you can actually invoke

A model defines behavior, such as on/off, dimming, sensors, scenes, or vendor commands.

In SDK code, model extension is where behavior becomes ergonomic:

import { GenericOnOff, SigModelId } from "@blemeshjs/sdk";

const node = mesh.configuredNodes?.[0];
if (!node) throw new Error("No configured node available");

const model = mesh.getModel(node.uuid.uuidString, 0, SigModelId.genericOnOffServerModelId);
if (!model) throw new Error("Generic OnOff model not found");

const onOff = model.use(GenericOnOff);
await onOff.set(true, { acknowledged: true });

Provisioning: from nearby device to trusted node

Provisioning is the secure onboarding process that adds a device to your mesh network.

Unprovisioned device
  -> discover
  -> connect
  -> identify and exchange security data
  -> assign address + keys
  -> save network state
  -> provisioned node

Provisioning matters because it changes persistent network state, not just UI state.

Publish/subscribe: one-to-one and one-to-many messaging

Models publish messages to addresses. Models subscribe to addresses.

Those addresses can represent one target, a group, or a virtual destination.

This is what lets one action control many devices.

Common mistakes to avoid

⚠️ Gotcha

Treating a node and model as the same thing is the fastest way to get confused. The node is the container, the model is the behavior.

Mistake	Better approach
Provisioning is "just onboarding UI"	Treat provisioning as a security + topology update
Sending one command per device for room control	Use group addressing for one-to-many control
Jumping into API reference first	Build the node/element/model model first

✅ Best practice

When debugging, always ask: "Am I at the right layer?" Node issue, model issue, or address issue.

If this clicked, you are ready to move to guided workflows.

Next, you will want to follow Setup Runtime, then Provision a New Device.

Core Concepts

On this page