> For the complete documentation index, see [llms.txt](https://docs.blynk.io/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blynk.io/en/html-widget-developer-guide/device-metadata.md).

# Device Metadata

Read and update the metadata fields of the bound device.

### The metadata descriptor

Every metadata method resolves with descriptors of this shape:

```ts
{
  id:           number,
  type:         string,          // 'Text' | 'Number' | 'List' | 'Location' | 'Contact' | 'Table' | …
  label:        string | null,
  description:  string | null,
  icon:         string | null,
  mandatory:    boolean,
  disabled:     boolean,
  editable:     boolean,         // can this user change it from a widget right now
  displayValue: string | null,   // host-formatted, for display only
  value:        object,          // type-specific — this is what updateDeviceMetadata patches
  schema:       object           // type-specific constraints for building controls
}
```

`editable` is `true` only when the user can edit devices, the field is user-editable and not disabled, **and** its type is patchable from a widget. Use `editable`, `disabled` and `schema` to build controls.

Common `value` / `schema` pairs:

| `type`                                 | `value`                                                                                     | `schema`                                                                        |
| -------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `Text`, `Email`, `Tz`, `DeviceName`, … | `{ value: string \| null }`                                                                 | `{ validationRegExp }` for `Text`, empty otherwise                              |
| `Int`, `Number`, `Measurement`         | `{ value: number }`                                                                         | `{ min, max, step }` (+ units/decimals for `Number`, `units` for `Measurement`) |
| `List`, `TemplateId`                   | `{ selectedOption: string \| null }`                                                        | `{ options: string[] \| null }`                                                 |
| `Location`                             | `{ orgLocationId, siteName, buildingName, floorName, unit, room, zone, placeId, lat, lon }` | `{ locationEnabled, enabledFields, useLocationDataFromDevice }`                 |
| `Contact` / `Address`                  | contact / address fields                                                                    | `{ enabledFields, defaultsEnabled }`                                            |
| `Table`                                | `{ selectedRowIndex: number }`                                                              | `{ headers, rows }`                                                             |
| `Coordinates`                          | `{ lat: number, lon: number }`                                                              | `{}`                                                                            |

A metadata type introduced by a newer server keeps its server type string in `type`, and its extra properties are preserved inside `value`.

**Which types a widget can update**

| Type                    | Patch properties                                                                                                | Rules                                                                                                               |
| ----------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `Text`                  | `value: string \| null`                                                                                         | Up to 255 characters; must match the field's `validationRegExp` when it has one                                     |
| `Email`                 | `value: string \| null`                                                                                         | Up to 200 characters; must be an email address                                                                      |
| `Tz`                    | `value: string \| null`                                                                                         | Up to 200 characters; must be a supported time zone ID                                                              |
| `DeviceName`            | `value: string \| null`                                                                                         | Up to 50 characters                                                                                                 |
| `Number`, `Measurement` | `value: number`                                                                                                 | Finite; within `[min, max]` when the field defines them                                                             |
| `Int`                   | `value: number`                                                                                                 | As `Number`, and an integer                                                                                         |
| `List`                  | `selectedOption: string \| null`                                                                                | One of the field's `options`                                                                                        |
| `Table`                 | `selectedRowIndex: number`                                                                                      | An integer row index of the field's table                                                                           |
| `Unit`                  | `selected: string \| null`                                                                                      | The field's `unitA` or `unitB`                                                                                      |
| `Contact`               | `firstName`, `lastName`, `email`, `phone`, `streetAddress`, `streetAddress2`, `country`, `city`, `state`, `zip` | Only properties enabled on the field; each `string \| null`, up to 200 characters; `email` must be an email address |
| `Location`              | `buildingName`, `floorName`, `unit`, `room`, `zone`                                                             | Only properties enabled on the field; each up to 200 characters                                                     |

Every other type is **read-only** from a widget, including `TemplateId`, `Coordinates`, `Address`, `Image`, `Switch`, `Cost`, `Time`, `Range`, `Shift`, `MultiText`, `DeviceReference`, `DeviceOwner` and the network-identifier types. `ApplicationKey`, `NetworkKey` and `OTASettings` are never exposed to widgets at all.

**Errors** — all metadata methods fail with a `BlynkBridgeError`:

| Code                                                     | When                                                                                               |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `invalid_selector`                                       | The selector isn't an object with exactly one of `id` (an integer) or `name` (1 to 255 characters) |
| `invalid_options`                                        | `options` isn't an object, or `options.refresh` isn't a boolean                                    |
| `invalid_request`                                        | `valuePatch` isn't a non-empty object                                                              |
| `invalid_property_type`                                  | A patch property is `undefined`, not JSON, or the wrong type for the field                         |
| `invalid_property_value`                                 | Right type, but fails a rule — length, range, option membership, format                            |
| `unknown_value_property`                                 | The patch has a property the field type doesn't accept                                             |
| `validation_failed`                                      | A field-level validator failed (regex pattern, options or rows not loaded)                         |
| `metadata_not_found`                                     | No field with that `id` or `name` on the bound device                                              |
| `ambiguous_metadata_name`                                | Several fields share that `name` — select by `id`                                                  |
| `metadata_access_denied`                                 | The field is never exposed to widgets, or the user may not edit device metadata                    |
| `metadata_disabled`                                      | The field is disabled                                                                              |
| `metadata_not_editable`                                  | The field isn't user-editable, or the widget is disabled                                           |
| `unsupported_metadata_type`                              | The field's type is read-only from a widget                                                        |
| `device_changed`                                         | The widget's binding changed before the call finished                                              |
| `device_not_loaded`                                      | The device's metadata couldn't be loaded                                                           |
| `request_timeout`                                        | No result within 30 seconds — a write's outcome is unknown, so re-read before retrying             |
| `server_error`, `device_unavailable`, `bridge_destroyed` | As for every request                                                                               |

`details` carries at least `{ id, property }` where they apply.

***

### Get all device metadata

> Returns every metadata field of the bound device that a widget may see.

```js
bridge.getAllDeviceMetadata(options?)  // → Promise<MetadataDescriptor[]>
```

**Parameters**

| Name              | Type      | Required | Description                                                                                                |
| ----------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `options.refresh` | `boolean` | no       | `true` waits for a fresh read from the server. Default `false` reuses the host's last full-device snapshot |

**Resolves with** an array of [descriptors](#the-metadata-descriptor).

**Rejects with** `invalid_options`, `device_changed`, `device_not_loaded`, `request_timeout` — see [Errors](https://docs.blynk.io/en/html-widget-developer-guide/device-metadata.md).

```js
const fields = await bridge.getAllDeviceMetadata();
fields.forEach(f => renderField(f.label, f.displayValue));
```

***

### Get a device metadata field

> Returns one metadata field of the bound device.

```js
bridge.getDeviceMetadata(selector, options?)  // → Promise<MetadataDescriptor>
```

**Parameters**

| Name              | Type      | Required | Description                                                                  |
| ----------------- | --------- | -------- | ---------------------------------------------------------------------------- |
| `selector`        | `object`  | yes      | Exactly one of `{ id: number }` or `{ name: string }` — the exact field name |
| `options.refresh` | `boolean` | no       | As for `getAllDeviceMetadata`                                                |

**Resolves with** one [descriptor](#the-metadata-descriptor).

**Rejects with** `invalid_selector`, `invalid_options`, `metadata_not_found`, `ambiguous_metadata_name`, `metadata_access_denied`, `device_changed`, `request_timeout`.

```js
const location = await bridge.getDeviceMetadata({ name: 'Installation location' });
```

***

### Update a device metadata field

> Changes one metadata field and resolves with the committed descriptor.

```js
bridge.updateDeviceMetadata(selector, valuePatch)  // → Promise<MetadataDescriptor>
```

**Parameters**

| Name         | Type     | Required | Description                                                                                                                                                                                      |
| ------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `selector`   | `object` | yes      | Exactly one of `{ id }` or `{ name }`                                                                                                                                                            |
| `valuePatch` | `object` | yes      | Non-empty object with only the [patch properties](#the-metadata-descriptor) of the field's type. Omitted properties stay unchanged; an explicit `null` is accepted only where the type allows it |

**Resolves with** the committed [descriptor](#the-metadata-descriptor), as stored on the server.

**Rejects with** any of the [metadata errors](https://docs.blynk.io/en/html-widget-developer-guide/device-metadata.md).

* Writes are queued per device and run one after another.
* A timed-out write has an unknown outcome: re-read before retrying.
* Use the **same property list for display and for editing**. A property you render but never patch, or the reverse, silently goes missing instead of erroring.

**Example**

```js
const location = await bridge.getDeviceMetadata({ name: 'Installation location' });
if (location.type === 'Location' && location.editable &&
    location.schema.enabledFields.includes('room')) {
  const committed = await bridge.updateDeviceMetadata({ id: location.id }, { room: '205' });
  renderMetadata(committed);
}
```

**Live updates** arrive in [`onDeviceMetadataUpdated`](https://docs.blynk.io/en/html-widget-developer-guide/callbacks.md), one committed descriptor at a time, including schema changes. A successful write can arrive both through its Promise and through the callback, so make rendering idempotent. Registering the callback doesn't replace an initial read.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.blynk.io/en/html-widget-developer-guide/device-metadata.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
