> 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.md).

# Device

Who and what the bound device is: its identity, status, image and tags. Every call targets the device the widget is bound to — JavaScript can't pass a device ID.

### Get device info

> Returns the bound device's ID, organization, name, status, last activity and image.

```js
bridge.getDeviceInfo()  // → Promise<DeviceInfo>
```

**Parameters:** none.

**Resolves with**

```ts
{
  id:             number | null,   // device ID; null when no device is bound
  orgId:          number | null,   // organization ID
  name:           string,          // device display name; '' when no device is bound
  status:         string,          // 'ONLINE' | 'OFFLINE' | a custom status | ''
  lastReportedAt: number | null,   // Unix ms of the last server activity
  image:          string | null    // absolute http(s) URL of the device image — see "Device image"
}
```

* The call always resolves with an object, also when no device is linked. Guard on `info.id`, not on `info` itself.
* `status` is a flat string — there is no nested status object. Compare case-insensitively: `info.status.toUpperCase() === 'ONLINE'`.
* There is no callback for device-info changes. Call `getDeviceInfo()` again when you need fresh status.

**Rejects with** `request_timeout` (web, after 10 seconds — `Device info request timeout (10s)`), `server_error`, `device_unavailable`, `bridge_destroyed`.

**Example**

```js
bridge.getDeviceInfo()
  .then(info => {
    if (!info || !info.id) { showNoDevice(); return; }

    nameEl.textContent = info.name;
    renderDeviceImage(info.image, info.name);   // see "Device image"

    const status = (info.status || '').toUpperCase();
    dot.className = status === 'ONLINE'  ? 'dot online'
                  : status === 'OFFLINE' ? 'dot offline'
                  : status               ? 'dot custom' : 'dot';
  })
  .catch(() => showNoDevice());
```

***

### Device image

> The device's photo comes with the device info — no separate call.

`getDeviceInfo().image` is an **absolute `http(s)` URL** of the device image, or `null` when the device has none.

* Set it as an `<img>` `src` from JavaScript. It's a URL the host hands you, so it works on every host, including the sandboxed web iframe.
* While the image loads, when `image` is `null`, and on an `error` event, show a neutral placeholder in the same box — the device name's initial, for example — never a broken-image icon.
* Don't hardcode or cache the URL across sessions: read it from `getDeviceInfo()` every time the widget loads.
* The image is read-only for a widget — the bridge has no method to change it. Files stored on the device are a separate thing; see [Device Files & Assets](https://docs.blynk.io/en/html-widget-developer-guide/device-files-and-assets.md).
* The URL is cross-origin, so don't draw it to a `<canvas>` and read pixels back.

**Example**

```html
<div class="avatar">
  <img id="device-photo" alt="" hidden>
  <span id="device-initial"></span>
</div>
```

```js
function renderDeviceImage(url, name) {
  const img = document.getElementById('device-photo');
  const initial = document.getElementById('device-initial');
  initial.textContent = (name || '?').trim().charAt(0).toUpperCase();

  if (!url) { img.hidden = true; initial.hidden = false; return; }

  img.onload  = () => { img.hidden = false; initial.hidden = true; };
  img.onerror = () => { img.hidden = true;  initial.hidden = false; };
  img.src = url;
}
```

```css
.avatar          { position: relative; width: 48px; height: 48px; border-radius: var(--radius);
                   overflow: hidden; background: var(--surface); display: grid; place-items: center; }
.avatar img      { width: 100%; height: 100%; object-fit: cover; }
```

***

### Get device tags

> Returns the tags assigned to the bound device.

```js
bridge.getDeviceTags()  // → Promise<Tag[]>
```

**Parameters:** none.

**Resolves with** an array of tags, `[]` when the device has none:

```ts
Array<{
  id:    number,
  name:  string,
  color: string,   // tag color — use it as an accent (a dot or bar), not as a text color
  icon:  string    // tag icon
}>
```

**Rejects with**

| Code                 | When                                                              |
| -------------------- | ----------------------------------------------------------------- |
| `too_many_requests`  | 50 tag requests from this widget are already pending              |
| `request_timeout`    | No result within 30 seconds (`Device tags request timeout (30s)`) |
| `server_error`       | The host failed without a specific code                           |
| `device_unavailable` | Called outside a Blynk host                                       |
| `bridge_destroyed`   | Called after `destroy()`                                          |

**Permission:** `VIEW_DEVICE_TAGS`. Feature-detect the method — an older host can lack it.

**Example**

```js
if (typeof bridge.getDeviceTags === 'function' &&
    await bridge.isPermissionAllowed('VIEW_DEVICE_TAGS').catch(() => true)) {
  const tags = await bridge.getDeviceTags().catch(() => []);
  tags.forEach(tag => {
    const chip = document.createElement('span');
    chip.className = 'chip';
    chip.style.setProperty('--chip-accent', tag.color);
    chip.textContent = tag.name;          // never innerHTML
    tagRow.appendChild(chip);
  });
}
```


---

# 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.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.
