From 4fc22847811f4db911bf7cd4fed77b2d6a406df0 Mon Sep 17 00:00:00 2001 From: Frederico Minuzzi Date: Mon, 18 May 2026 15:57:43 -0300 Subject: [PATCH 1/5] docs(image-marker-widget): expand documentation with layers, geofence, and pin format details --- .gitignore | 1 + .../map-and-location/image-marker-widget.md | 255 ++++++++++++++---- 2 files changed, 206 insertions(+), 50 deletions(-) diff --git a/.gitignore b/.gitignore index 304b938b..9c96e263 100644 --- a/.gitignore +++ b/.gitignore @@ -24,6 +24,7 @@ dist/ # Misc .DS_Store +.mcp.json # Environment .env diff --git a/docs/tagoio/widgets/map-and-location/image-marker-widget.md b/docs/tagoio/widgets/map-and-location/image-marker-widget.md index 3bb3cd95..4ce6527a 100644 --- a/docs/tagoio/widgets/map-and-location/image-marker-widget.md +++ b/docs/tagoio/widgets/map-and-location/image-marker-widget.md @@ -1,98 +1,253 @@ --- title: "Image Marker Widget" -description: "A short guide to the Image Marker widget in TagoIO, explaining its purpose, configurable features, and how to add and customize it on a dashboard." +description: "Learn how to use the Image Marker widget in TagoIO to place pins on floor plans, track indoor device positions, and configure layers, geofences, and infoboxes." tags: ["tagoio", "widgets"] -keywords: [tagoio, iot, widget, image marker, location] +keywords: [tagoio, iot, widget, image marker, location, indoor tracking, floor plan, pin] --- -The image marker widget allows you to place pins on images and customize each pin's color, value, and icon. Use it to annotate floor plans, maps, and other visuals with live or historical data. +The Image Marker widget lets you place pins on any image — floor plans, building maps, facility diagrams — and connect each pin to live or historical device data. It is the standard choice for **indoor device tracking**, where GPS coordinates are unavailable and device positions are defined relative to a custom image. ![Image marker example showing pins on a floor plan](/docs_imagem/tagoio/image-marker-widget-2.png) -This widget also accepts features like [metadata](/docs/tagoio/devices/payload-parser/metadata.md) and [groups](/docs/tagoio/devices/grouping-variables.md), which can be set in your variable data to alter how the widget behaves. +To use this widget you need at least two things: + +- **A pin data variable** — the device variable whose value is shown on the pin (e.g., temperature, status). +- **A layers variable** — a variable that stores the floor plan image and the `x`/`y` position of each pin for each layer. + +Optionally, you can also configure a **geofence variable** to store the boundaries users draw on the image. ## Creating your own -To add the widget to your dashboard, choose the Image Marker widget from the widget list and customize it to your preference. You can edit it by configuring the options located on the right side of the widget. +To add the widget to your dashboard, choose Image Marker from the widget list. Configure it using the options panel in the edit panel. ### 1. 'Data From' Field -This field allows you to set the device and variable that will be used in this widget. -The widget requires **at least two variables**: one for the pin’s data (e.g., temperature, status) and another to store all pin positions on the image. +This field sets which device variables supply pin data. You can add up to **30 devices**. + +> If you need more than 30 pins, use Advanced mode with a single device that accumulates the last known position of each tracked device as separate [groups](/docs/tagoio/devices/grouping-variables.md). + +- **Normal Dashboards** — select a device and the variable that holds pin data. +- **Blueprint Dashboards** — add the Blueprint device and type the variable name. The selector may appear empty because the dashboard does not yet know which devices are linked to the Blueprint. + +#### Layer Variable + +Below the main **Data From** selector there is a **"Variable used to store layers"** field. Set it to the variable that holds the floor plan image for each layer. When a user uploads or replaces a floor plan image via the editor, the new image URL is written back to this variable automatically. + +#### Geofence Variable -- **Normal Dashboards** – Select a device from your list of devices and choose the variable that contains the pin data. -- **Blueprint Dashboards** – Add the Blueprint device and input the name of the variable that holds the information. Because the dashboard does not yet know which devices are linked to the Blueprint, the variable selector may initially appear empty. +The **"Geofence variable"** field sets the variable where geofence boundaries are saved. When users draw polygons or circles in the editor, the shapes are written to this variable automatically. See [Geofence](#8-geofence) for the full data format. ### 2. Image Marker Behavior Modes -The widget has two behavior types: +The widget has two modes. Both store pin positions identically in the layer variable — the difference is how the editor presents options when you assign a pin: -| Mode | Description | -| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Basic** | Each pin corresponds to a distinct device. If you add multiple variables from the same device, they will appear in the same pin’s infobox. The number of pins is limited by the number of devices added. | -| **Advanced** | A single variable can produce multiple pins. This mode is useful when coordinates are updated continuously via a Device or Analysis. Variables can contain groups; each group creates its own pin, allowing one device to display many pins. | +| Mode | Description | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Basic** | When placing a pin in the editor, the widget shows the **devices** from the Data From field as assignment options. Each device gets one pin. Use this for simple setups where each physical device maps to one marker. | +| **Advanced** | When placing a pin in the editor, the widget shows all occurrences of the selected **variable** that have different [groups](/docs/tagoio/devices/grouping-variables.md) as assignment options. This lets a single device drive multiple pins — one per distinct group. Use this when one device reports multiple positions or when you need more than 30 pins. | ### 3. Positioning Pins -To position a pin you need to set an **x** and **y** coordinate for your variable data. These numbers represent the relative position on the image: (0, 0) is the top‑left corner and (1, 1) is the bottom‑right corner. +Pin positions are stored in the **layer variable** (see [Layer](#4-layer)), not in the device variable itself. The layer variable's `fixed_position` map holds the `x`/`y` coordinates for every pin. These are relative coordinates where `(0, 0)` is the top-left corner of the image and `(1, 1)` is the bottom-right corner. + +Each key in `fixed_position` is the **device ID concatenated with the group ID** of the variable assigned to that pin. See [Layer](#4-layer) for the full format. + +#### Using the Pin Position Editor + +You can position pins visually using the built-in editor, without editing variable data directly. This is useful for initial setup or quick adjustments. See [Editor](#5-editor) for details. + +### 4. Layer + +A layer is a background image on which pins and geofences are drawn. You can have multiple layers — for example, one per floor of a building — each with its own set of pins. + +Each layer has its own dedicated variable. In the widget configuration, you assign one **"Variable used to store layers"** per layer. That variable stores both the floor plan image URL and the current pin positions in a `fixed_position` map. -#### 3.1 Using Metadata +#### fixed_position key format -The selected variable must include `x` and `y` parameters inside its metadata: +The key format in `fixed_position` depends on the mode: + +- **Basic mode** — the key is the **device ID** alone. +- **Advanced mode** — the key is the **device ID concatenated with the group ID** of the variable assigned to that pin. + +**Basic mode** — key is just the device ID: ```json { - "fixed_position": { - "66f16881c903480009ff1042465c78a000c39bee89461786": { - "device": "66f16881c903480009ff1042", - "label": "Temperature", - "icon": "[https://svg.internal.tago.io/adjust.svg]", - "img_pin": "google.com", - "link_type": "image", - "value": 71, - "x": "0.4863223293768546", - "y": "0.5155412946428571" + "id": "", + "time": "", + "value": "Layer #1", + "variable": "layer", + "metadata": { + "changed_pins": [""], + "fixed_position": { + "": { + "device": "", + "label": "", + "link_type": "image", + "x": "0.49333079268292684", + "y": "0.4043542074363992" + } + }, + "file": { + "url": "", + "path": "" } }, - "file": { - "url": "[https://api.tago.io/file/635882e523251c00110779fa/buckets/66f16881c903480009ff1042/image.png]", - "path": "/buckets/66f16881c903480009ff1042/image.png" - } + "created_at": "", + "group": "", + "device": "" } ``` -> **Note:** The metadata format differs between advanced and basic mode. - -#### 3.2 Using the Pin Position Editor +**Advanced mode** — key is device ID + group ID: -You can enable an editor so users can place pin positions, edit infobox content, and more directly on the image. This is especially useful for quick adjustments without editing variable data. - -### 4. Layer +```json +{ + "id": "", + "time": "", + "value": "Layer #1", + "variable": "layer", + "metadata": { + "changed_pins": [], + "fixed_position": { + "": { + "device": "", + "link_type": "image", + "value": "", + "x": "0.5965083073727934", + "y": "0.3530265748031496" + }, + "": { + "device": "", + "link_type": "image", + "value": "", + "x": "0.2943276220145379", + "y": "0.26798720472440946" + } + }, + "file": { + "url": "", + "path": "" + } + }, + "created_at": "", + "group": "", + "device": "" +} +``` -Each layer represents a background image; you can add multiple layers, each maintaining its own set of pins. Layers can be created or edited from the top of the editor screen. The pencil icon allows you to edit layer information such as name and uploaded image. Dragging an image onto the editor replaces the current layer image. +Layers are managed at the top of the editor screen. The pencil icon opens a panel to rename the layer or replace its image. Dragging an image file onto the editor replaces the current layer's image. ### 5. Editor -The editor lets users modify layers, pins, and geofences if editing permissions are enabled. It appears as a pencil icon on the top‑left of the widget. Changes are saved by clicking the save button; otherwise they are discarded. The editor includes a toolbox with four main tools: +The editor lets users place and adjust pins, manage layers, and draw geofences. It is enabled via the pencil icon in the top-left corner of the widget. Changes only take effect after clicking **Save** — closing without saving discards all changes. + +The toolbox contains four tools: -- **Default tool** – Zoom and move the image. -- **Add tool** – Click on the image to add a pin (number of pins limited by data passed). -- **Edit tool** – Click an existing pin to edit its source, label, icon, etc. -- **Delete tool** – Remove a pin. +- **Default tool** — zoom and pan the image. +- **Add tool** — click on the image to place a new pin. The number of available pins is limited by the number of data entries. +- **Edit tool** — click an existing pin to change its variable, label, or icon. +- **Delete tool** — remove a pin. ### 6. Infobox -An infobox automatically associates with each pin and can be customized with images, external links, formulas, embedded widgets, and more. It provides contextual information when a user clicks on a pin. +Each pin has an infobox that opens when clicked. It shows the variable's value and can be customized with: + +- **Image** — display a static or dynamic image alongside the data. +- **External link** — add a button that opens a URL. +- **Formula** — transform the displayed value using a math expression. +- **Embedded widget** — embed a secondary widget inside the infobox. ### 7. Filters -Filters allow users to narrow displayed pins by **device**, **variable**, or **value**. A table lists all currently visible pins, making it easier to analyze data subsets. +Filters let users narrow down which pins are visible. You can filter by **device**, **variable**, or **value**. A table below the filters lists all visible pins — clicking a row centers the view on that pin. ### 8. Geofence -Geofences let you draw colored geographic boundaries on the image to visualize device trajectories within a zone. When enabled, the geofence can be edited via the tab in the upper right corner of the editor. Tools available include: +Geofences are colored boundaries (polygons or circles) drawn on the image. Use them to define zones and detect when a tracked device enters or leaves one. + +Before users can create geofences, you must configure at least one **event** in the widget settings. An event defines what trigger to associate with the geofence (for example, "enter" or "leave"). You can hardcode event options directly in the widget settings or supply them from a variable. + +When using a variable, each entry represents one event option. The `value` field is the event identifier: + +```json +[ + { + "variable": "event", + "value": "enter" + }, + { + "variable": "event", + "value": "leave" + } +] +``` + +When enabled, the geofence tools appear in the upper-right corner of the editor: + +- **Draw polygon** — click points to define a shape; click the first point to close it. +- **Draw circle** — click the center, then click again to set the radius. +- **Edit tool** — modify an existing polygon or circle. +- **Delete tool** — remove a geofence. + +Each geofence is saved as its own separate entry in the geofence variable. The shape type determines the format of the `coordinates` field. + +**Circle geofence** — `coordinates` is a single center point `{x, y}`, and `radius` is the size (both in the 0–1 range): + +```json +{ + "id": "6a03663c07bf4d000cb4516b", + "time": "2026-05-12T17:41:16.311Z", + "value": "Geofence #2", + "variable": "geofence", + "metadata": { + "coordinates": { + "x": 0.45642229087452474, + "y": 0.3955462598425197 + }, + "radius": 0.09320854807801622, + "type": "circle", + "value": "Geofence #2", + "event": "enter", + "eventDescription": "enter", + "eventColor": "", + "layer": "5rzZEJza2e0f4LNs7OuEp" + }, + "created_at": "2026-05-12T17:41:16.311Z", + "group": "-WCGck62fw9g6DJLAHHdy", + "device": "66f16881c903480009ff1042" +} +``` + +**Polygon geofence** — `coordinates` is an array of `{x, y}` vertices: + +```json +{ + "id": "6a0366332259ff000bbb49c3", + "time": "2026-05-12T17:41:07.363Z", + "value": "Geofence #1", + "variable": "geofence", + "metadata": { + "coordinates": [ + { "x": 0.4145971958174905, "y": 0.058538385826771656 }, + { "x": 0.6275249524714829, "y": 0.08373523622047244 }, + { "x": 0.5666884505703422, "y": 0.19712106299212598 }, + { "x": 0.430756891634981, "y": 0.181373031496063 }, + { "x": 0.32619415399239543, "y": 0.09318405511811023 }, + { "x": 0.43360860266159695, "y": 0.06956200787401574 } + ], + "type": "polygon", + "value": "Geofence #1", + "event": "leave", + "eventDescription": "leave", + "eventColor": "", + "layer": "5rzZEJza2e0f4LNs7OuEp" + }, + "created_at": "2026-05-12T17:41:07.363Z", + "group": "bvHWspJH_6BJad7lYlQsD", + "device": "66f16881c903480009ff1042" +} +``` + +> **Note:** All coordinates are relative to the image dimensions (range 0–1), not geographic coordinates. The `layer` field references the layer this geofence belongs to using the variable group. -- **Draw polygon** – Click points to form a shape; finish by clicking the first point. -- **Draw circle** – Click center then another point for radius. -- **Edit tool** – Modify existing polygons or circles. -- **Delete tool** – Remove geofences. From dc6d19259534170e0ebd735818d0b6307a1bbd3e Mon Sep 17 00:00:00 2001 From: Frederico Minuzzi Date: Mon, 18 May 2026 16:06:05 -0300 Subject: [PATCH 2/5] docs(image-marker-widget): fix table and trailing whitespace formatting --- .../widgets/map-and-location/image-marker-widget.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/tagoio/widgets/map-and-location/image-marker-widget.md b/docs/tagoio/widgets/map-and-location/image-marker-widget.md index 4ce6527a..cb0919db 100644 --- a/docs/tagoio/widgets/map-and-location/image-marker-widget.md +++ b/docs/tagoio/widgets/map-and-location/image-marker-widget.md @@ -41,9 +41,9 @@ The **"Geofence variable"** field sets the variable where geofence boundaries ar The widget has two modes. Both store pin positions identically in the layer variable — the difference is how the editor presents options when you assign a pin: -| Mode | Description | -| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Basic** | When placing a pin in the editor, the widget shows the **devices** from the Data From field as assignment options. Each device gets one pin. Use this for simple setups where each physical device maps to one marker. | +| Mode | Description | +| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Basic** | When placing a pin in the editor, the widget shows the **devices** from the Data From field as assignment options. Each device gets one pin. Use this for simple setups where each physical device maps to one marker. | | **Advanced** | When placing a pin in the editor, the widget shows all occurrences of the selected **variable** that have different [groups](/docs/tagoio/devices/grouping-variables.md) as assignment options. This lets a single device drive multiple pins — one per distinct group. Use this when one device reports multiple positions or when you need more than 30 pins. | ### 3. Positioning Pins @@ -232,7 +232,7 @@ Each geofence is saved as its own separate entry in the geofence variable. The s { "x": 0.4145971958174905, "y": 0.058538385826771656 }, { "x": 0.6275249524714829, "y": 0.08373523622047244 }, { "x": 0.5666884505703422, "y": 0.19712106299212598 }, - { "x": 0.430756891634981, "y": 0.181373031496063 }, + { "x": 0.430756891634981, "y": 0.181373031496063 }, { "x": 0.32619415399239543, "y": 0.09318405511811023 }, { "x": 0.43360860266159695, "y": 0.06956200787401574 } ], @@ -250,4 +250,3 @@ Each geofence is saved as its own separate entry in the geofence variable. The s ``` > **Note:** All coordinates are relative to the image dimensions (range 0–1), not geographic coordinates. The `layer` field references the layer this geofence belongs to using the variable group. - From c6233316010916a24466650f4a803724f8ed63f2 Mon Sep 17 00:00:00 2001 From: Frederico Minuzzi Date: Tue, 19 May 2026 16:50:56 -0300 Subject: [PATCH 3/5] docs(image-marker-widget): address PR review feedback - Trim description to under 160 chars - Rewrite opening paragraph to front-load the outcome - Add How it works workflow overview - Rename section 2 to Basic vs. Advanced Mode - Slim down mode table descriptions - Merge Positioning Pins as subsection of Layer; renumber sections - Clarify fixed_position key concatenation with concrete example - Add coordinate percentage hint - Add Limit/Workaround blockquotes for the 30-device cap - Trim system fields from layer and geofence JSON examples - Move Save warning to caution admonition at top of Editor section - Group Infobox, Filters, Geofence under Additional features - Add cross-links: Blueprint Dashboards, Blueprint device, metadata, Formula, Geofence Actions, Map widget geofences, Dashboards, Widgets - Remove .md extension from grouping-variables links - Clarify Geofence Options tab and eventColor hex usage --- .../map-and-location/image-marker-widget.md | 116 ++++++++---------- 1 file changed, 53 insertions(+), 63 deletions(-) diff --git a/docs/tagoio/widgets/map-and-location/image-marker-widget.md b/docs/tagoio/widgets/map-and-location/image-marker-widget.md index cb0919db..26e2d10a 100644 --- a/docs/tagoio/widgets/map-and-location/image-marker-widget.md +++ b/docs/tagoio/widgets/map-and-location/image-marker-widget.md @@ -1,11 +1,11 @@ --- title: "Image Marker Widget" -description: "Learn how to use the Image Marker widget in TagoIO to place pins on floor plans, track indoor device positions, and configure layers, geofences, and infoboxes." +description: "Place pins on floor plans, track indoor devices, and configure layers and geofences with the Image Marker widget." tags: ["tagoio", "widgets"] keywords: [tagoio, iot, widget, image marker, location, indoor tracking, floor plan, pin] --- -The Image Marker widget lets you place pins on any image — floor plans, building maps, facility diagrams — and connect each pin to live or historical device data. It is the standard choice for **indoor device tracking**, where GPS coordinates are unavailable and device positions are defined relative to a custom image. +The Image Marker widget places pins on custom images — floor plans, building maps, facility diagrams — and connects each pin to live or historical device data. It's the standard choice for **indoor device tracking**, where GPS isn't available and positions are defined relative to an image. ![Image marker example showing pins on a floor plan](/docs_imagem/tagoio/image-marker-widget-2.png) @@ -16,18 +16,28 @@ To use this widget you need at least two things: Optionally, you can also configure a **geofence variable** to store the boundaries users draw on the image. +## How it works + +1. Add the Image Marker widget to a [dashboard](/docs/tagoio/dashboards/). +2. Configure the **Data From** field with your pin data variables. +3. Set a **layer variable** to store the floor plan image and pin positions. +4. Use the **editor** to visually place pins on the image. +5. Optionally, draw geofences to define zones. + ## Creating your own -To add the widget to your dashboard, choose Image Marker from the widget list. Configure it using the options panel in the edit panel. +To add the widget to your dashboard, choose Image Marker from the [widget list](/docs/tagoio/widgets/). Configure it using the options panel in the edit panel. ### 1. 'Data From' Field -This field sets which device variables supply pin data. You can add up to **30 devices**. +This field sets which device variables supply pin data. -> If you need more than 30 pins, use Advanced mode with a single device that accumulates the last known position of each tracked device as separate [groups](/docs/tagoio/devices/grouping-variables.md). +> **Limit:** The Data From field supports up to 30 devices. +> +> **Workaround:** To display more than 30 pins, use Advanced mode. Configure a single device that stores each tracked device's position as a separate [group](/docs/tagoio/devices/grouping-variables). Each group becomes its own pin. - **Normal Dashboards** — select a device and the variable that holds pin data. -- **Blueprint Dashboards** — add the Blueprint device and type the variable name. The selector may appear empty because the dashboard does not yet know which devices are linked to the Blueprint. +- **[Blueprint Dashboards](/docs/tagoio/dashboards/blueprint-dashboard)** — add the [Blueprint device](/docs/tagoio/devices/blueprint-devices-entities) and type the variable name. The selector may appear empty because the dashboard does not yet know which devices are linked to the Blueprint. #### Layer Variable @@ -35,28 +45,18 @@ Below the main **Data From** selector there is a **"Variable used to store layer #### Geofence Variable -The **"Geofence variable"** field sets the variable where geofence boundaries are saved. When users draw polygons or circles in the editor, the shapes are written to this variable automatically. See [Geofence](#8-geofence) for the full data format. +The **"Geofence variable"** field sets the variable where geofence boundaries are saved. When users draw polygons or circles in the editor, the shapes are written to this variable automatically. See [Geofence](#geofence) for the full data format. -### 2. Image Marker Behavior Modes +### 2. Basic vs. Advanced Mode The widget has two modes. Both store pin positions identically in the layer variable — the difference is how the editor presents options when you assign a pin: -| Mode | Description | -| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Basic** | When placing a pin in the editor, the widget shows the **devices** from the Data From field as assignment options. Each device gets one pin. Use this for simple setups where each physical device maps to one marker. | -| **Advanced** | When placing a pin in the editor, the widget shows all occurrences of the selected **variable** that have different [groups](/docs/tagoio/devices/grouping-variables.md) as assignment options. This lets a single device drive multiple pins — one per distinct group. Use this when one device reports multiple positions or when you need more than 30 pins. | - -### 3. Positioning Pins - -Pin positions are stored in the **layer variable** (see [Layer](#4-layer)), not in the device variable itself. The layer variable's `fixed_position` map holds the `x`/`y` coordinates for every pin. These are relative coordinates where `(0, 0)` is the top-left corner of the image and `(1, 1)` is the bottom-right corner. - -Each key in `fixed_position` is the **device ID concatenated with the group ID** of the variable assigned to that pin. See [Layer](#4-layer) for the full format. - -#### Using the Pin Position Editor +| Mode | Description | +| ------------ | ----------- | +| **Basic** | The editor shows the **devices** from the Data From field as pin assignment options. Each device gets one pin. Use this for simple setups where each physical device maps to one marker. | +| **Advanced** | The editor shows all occurrences of the selected **variable** that have different [groups](/docs/tagoio/devices/grouping-variables) as options. Each group becomes a separate pin. Use this when a single device reports multiple positions or when you need more than 30 pins. | -You can position pins visually using the built-in editor, without editing variable data directly. This is useful for initial setup or quick adjustments. See [Editor](#5-editor) for details. - -### 4. Layer +### 3. Layer A layer is a background image on which pins and geofences are drawn. You can have multiple layers — for example, one per floor of a building — each with its own set of pins. @@ -67,18 +67,17 @@ Each layer has its own dedicated variable. In the widget configuration, you assi The key format in `fixed_position` depends on the mode: - **Basic mode** — the key is the **device ID** alone. -- **Advanced mode** — the key is the **device ID concatenated with the group ID** of the variable assigned to that pin. +- **Advanced mode** — the key is the **device ID immediately followed by the group ID, with no separator**. For example, if the device ID is `abc123` and the group is `xyz789`, the key is `abc123xyz789`. + +> The fields you configure are inside the [`metadata`](/docs/tagoio/devices/payload-parser/metadata) object: `fixed_position` (pin positions) and `file` (the floor plan image URL). System fields (`id`, `time`, `created_at`) are added automatically. **Basic mode** — key is just the device ID: ```json { - "id": "", - "time": "", "value": "Layer #1", "variable": "layer", "metadata": { - "changed_pins": [""], "fixed_position": { "": { "device": "", @@ -92,23 +91,17 @@ The key format in `fixed_position` depends on the mode: "url": "", "path": "" } - }, - "created_at": "", - "group": "", - "device": "" + } } ``` -**Advanced mode** — key is device ID + group ID: +**Advanced mode** — key is device ID + group ID (no separator): ```json { - "id": "", - "time": "", "value": "Layer #1", "variable": "layer", "metadata": { - "changed_pins": [], "fixed_position": { "": { "device": "", @@ -129,18 +122,25 @@ The key format in `fixed_position` depends on the mode: "url": "", "path": "" } - }, - "created_at": "", - "group": "", - "device": "" + } } ``` Layers are managed at the top of the editor screen. The pencil icon opens a panel to rename the layer or replace its image. Dragging an image file onto the editor replaces the current layer's image. -### 5. Editor +#### Positioning pins + +Pin positions are stored in the `fixed_position` map of the layer variable, not in the device variable itself. Coordinates are relative to the image dimensions: `(0, 0)` is the top-left corner and `(1, 1)` is the bottom-right corner. Think of them as percentages — `x: 0.5` means the pin is at 50% of the image width. + +You can set positions visually using the built-in editor without editing variable data directly. See [Editor](#4-editor) for details. + +### 4. Editor + +:::caution +Changes only take effect after clicking **Save**. Closing without saving discards all changes. +::: -The editor lets users place and adjust pins, manage layers, and draw geofences. It is enabled via the pencil icon in the top-left corner of the widget. Changes only take effect after clicking **Save** — closing without saving discards all changes. +The editor lets users place and adjust pins, manage layers, and draw geofences. It is enabled via the pencil icon in the top-left corner of the widget. The toolbox contains four tools: @@ -149,24 +149,26 @@ The toolbox contains four tools: - **Edit tool** — click an existing pin to change its variable, label, or icon. - **Delete tool** — remove a pin. -### 6. Infobox +## Additional features + +### Infobox Each pin has an infobox that opens when clicked. It shows the variable's value and can be customized with: - **Image** — display a static or dynamic image alongside the data. - **External link** — add a button that opens a URL. -- **Formula** — transform the displayed value using a math expression. -- **Embedded widget** — embed a secondary widget inside the infobox. +- **[Formula](/docs/tagoio/widgets/general/formula)** — transform the displayed value using a math expression. +- **Embedded widget** — embed any dashboard widget inside the infobox. -### 7. Filters +### Filters Filters let users narrow down which pins are visible. You can filter by **device**, **variable**, or **value**. A table below the filters lists all visible pins — clicking a row centers the view on that pin. -### 8. Geofence +### Geofence -Geofences are colored boundaries (polygons or circles) drawn on the image. Use them to define zones and detect when a tracked device enters or leaves one. +Geofences are colored boundaries (polygons or circles) drawn on the image. Use them to define zones and detect when a tracked device enters or leaves one. You can also trigger [Actions](/docs/tagoio/actions/trigger-by-geofence) based on geofence events, similar to [geofences in the Map widget](/docs/tagoio/widgets/map-and-location/map-widget/geofences-in-map-widgets). -Before users can create geofences, you must configure at least one **event** in the widget settings. An event defines what trigger to associate with the geofence (for example, "enter" or "leave"). You can hardcode event options directly in the widget settings or supply them from a variable. +Before users can create geofences, you must configure at least one **event** in the **Geofence Options** tab of the widget settings. An event defines what trigger to associate with the geofence (for example, "enter" or "leave"). You can hardcode event options directly in the widget settings or supply them from a variable. When using a variable, each entry represents one event option. The `value` field is the event identifier: @@ -196,8 +198,6 @@ Each geofence is saved as its own separate entry in the geofence variable. The s ```json { - "id": "6a03663c07bf4d000cb4516b", - "time": "2026-05-12T17:41:16.311Z", "value": "Geofence #2", "variable": "geofence", "metadata": { @@ -207,15 +207,11 @@ Each geofence is saved as its own separate entry in the geofence variable. The s }, "radius": 0.09320854807801622, "type": "circle", - "value": "Geofence #2", "event": "enter", "eventDescription": "enter", "eventColor": "", "layer": "5rzZEJza2e0f4LNs7OuEp" - }, - "created_at": "2026-05-12T17:41:16.311Z", - "group": "-WCGck62fw9g6DJLAHHdy", - "device": "66f16881c903480009ff1042" + } } ``` @@ -223,8 +219,6 @@ Each geofence is saved as its own separate entry in the geofence variable. The s ```json { - "id": "6a0366332259ff000bbb49c3", - "time": "2026-05-12T17:41:07.363Z", "value": "Geofence #1", "variable": "geofence", "metadata": { @@ -237,16 +231,12 @@ Each geofence is saved as its own separate entry in the geofence variable. The s { "x": 0.43360860266159695, "y": 0.06956200787401574 } ], "type": "polygon", - "value": "Geofence #1", "event": "leave", "eventDescription": "leave", "eventColor": "", "layer": "5rzZEJza2e0f4LNs7OuEp" - }, - "created_at": "2026-05-12T17:41:07.363Z", - "group": "bvHWspJH_6BJad7lYlQsD", - "device": "66f16881c903480009ff1042" + } } ``` -> **Note:** All coordinates are relative to the image dimensions (range 0–1), not geographic coordinates. The `layer` field references the layer this geofence belongs to using the variable group. +> **Note:** All coordinates are relative to the image dimensions (range 0–1), not geographic coordinates. The `layer` field references the layer this geofence belongs to using the variable group. Set `eventColor` to a hex value (e.g., `#ff0000`) to color-code the geofence boundary; leave it empty to use the default color. From 1d49b1579a6ce9a2597af9ba370b9ac1a683ba8d Mon Sep 17 00:00:00 2001 From: Frederico Minuzzi Date: Tue, 19 May 2026 16:53:11 -0300 Subject: [PATCH 4/5] docs(image-marker-widget): fix table column alignment --- docs/tagoio/widgets/map-and-location/image-marker-widget.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tagoio/widgets/map-and-location/image-marker-widget.md b/docs/tagoio/widgets/map-and-location/image-marker-widget.md index 26e2d10a..e83a3fe5 100644 --- a/docs/tagoio/widgets/map-and-location/image-marker-widget.md +++ b/docs/tagoio/widgets/map-and-location/image-marker-widget.md @@ -51,9 +51,9 @@ The **"Geofence variable"** field sets the variable where geofence boundaries ar The widget has two modes. Both store pin positions identically in the layer variable — the difference is how the editor presents options when you assign a pin: -| Mode | Description | -| ------------ | ----------- | -| **Basic** | The editor shows the **devices** from the Data From field as pin assignment options. Each device gets one pin. Use this for simple setups where each physical device maps to one marker. | +| Mode | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Basic** | The editor shows the **devices** from the Data From field as pin assignment options. Each device gets one pin. Use this for simple setups where each physical device maps to one marker. | | **Advanced** | The editor shows all occurrences of the selected **variable** that have different [groups](/docs/tagoio/devices/grouping-variables) as options. Each group becomes a separate pin. Use this when a single device reports multiple positions or when you need more than 30 pins. | ### 3. Layer From 2b1c0ee1ad25a4850fbcbdb2a851c8265b065a32 Mon Sep 17 00:00:00 2001 From: Frederico Minuzzi Date: Tue, 19 May 2026 16:55:15 -0300 Subject: [PATCH 5/5] docs(image-marker-widget): reword 30-device note to remove workaround framing --- docs/tagoio/widgets/map-and-location/image-marker-widget.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/tagoio/widgets/map-and-location/image-marker-widget.md b/docs/tagoio/widgets/map-and-location/image-marker-widget.md index e83a3fe5..af123f09 100644 --- a/docs/tagoio/widgets/map-and-location/image-marker-widget.md +++ b/docs/tagoio/widgets/map-and-location/image-marker-widget.md @@ -32,9 +32,7 @@ To add the widget to your dashboard, choose Image Marker from the [widget list]( This field sets which device variables supply pin data. -> **Limit:** The Data From field supports up to 30 devices. -> -> **Workaround:** To display more than 30 pins, use Advanced mode. Configure a single device that stores each tracked device's position as a separate [group](/docs/tagoio/devices/grouping-variables). Each group becomes its own pin. +> **Note:** The Data From field supports up to 30 devices. To display more than 30 pins, use Advanced mode — configure a single device that stores each tracked device's position as a separate [group](/docs/tagoio/devices/grouping-variables). Each group becomes its own pin. - **Normal Dashboards** — select a device and the variable that holds pin data. - **[Blueprint Dashboards](/docs/tagoio/dashboards/blueprint-dashboard)** — add the [Blueprint device](/docs/tagoio/devices/blueprint-devices-entities) and type the variable name. The selector may appear empty because the dashboard does not yet know which devices are linked to the Blueprint.