Skip to content

Add sensors to the Traccar Server documentation #31624

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Mar 20, 2024
Merged

Add sensors to the Traccar Server documentation #31624

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ec27618
Add sensors to the Traccar Server documentation
ludeeus Feb 26, 2024
162ce11
Update YAML examples
ludeeus Feb 26, 2024
1910854
Tiny style tweaks
c0ffeeca7 Mar 15, 2024
900a6c7
Update source/_integrations/traccar_server.markdown
c0ffeeca7 Mar 15, 2024
429c129
Add name examples
ludeeus Mar 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 121 additions & 20 deletions source/_integrations/traccar_server.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ These device representations in Home Assistant will have [entities](#entities) a
The traccar server integration will create entities in with the following domains:

- [Device Tracker](/integrations/device_tracker)
- [Sensor](/integrations/sensor)

For more details about each of these, see the sections below.

Expand All @@ -103,22 +104,10 @@ State:
In addition to the custom attributes you can define in the Traccar Server integration options, the device tracker entity will have the following attributes:

{% configuration_basic %}
Address:
description: If a position update has an address associated with it, this will be the address.
Altitude:
description: The altitude of the position update.
Battery Level:
description: The battery level of the device if defined.
Category:
description: The category of the device in Traccar if defined.
Geofence:
description: The name of the geofence the device is located in.
Motion:
description: If the device is moving or not.
Speed:
description: The speed of the device.
Status:
description: The status of the device in Traccar.
Traccar ID:
description: The ID of the device in Traccar.
Tracker:
Expand All @@ -127,6 +116,120 @@ Tracker:

{% enddetails %}

### Sensor - Address

The Traccar Server integration will create a [sensor](/integrations/sensor) entity for each device registered in Traccar Server to show the address reported by the Traccar Server.

This entity is disabled by default.

{% configuration_basic %}
Name:
description: The name of the sensor will be set to what you have named it in Traccar Server followed by Address. If your device is named "Millennium Falcon", this will be "Millennium Falcon Address".
Entity ID:
description: This will be a slugified version of the name.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think an example could be helpful here, as well.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As we can not guarantee this, I think adding that can cause more confusion.
If you have to sensors that want the same entity ID, the second one to be loaded will get a _2 suffix.

Unique ID:
description: This will be the unique ID of the device tracker in Traccar Server followed by `position_address`.
State:
description: This will be the address reported by the Traccar Server, if geo detection is not configured this will be unknown`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: This will be the address reported by the Traccar Server, if geo detection is not configured this will be unknown`.
description: This will be the address reported by the Traccar Server, if geofence is not configured, this will be unknown`.

Should this be geofence? This is the only occurrence of geo detection I find here. or is this something else?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Geo detection is a setting that needs to be enabled on the server.

{% endconfiguration_basic %}

This entity does not have any attributes.

### Sensor - Altitude

The Traccar Server integration will create a [sensor](/integrations/sensor) entity for each device registered in Traccar Server to show the altitude reported by the Traccar Server.

This entity is disabled by default.

{% configuration_basic %}
Name:
description: The name of the sensor will be set to what you have named it in Traccar Server followed by Altitude. If your device is named "Millennium Falcon", this will be "Millennium Falcon Altitude".
Entity ID:
description: This will be a slugified version of the name.
Unique ID:
description: This will be the unique ID of the device tracker in Traccar Server followed by `position_altitude`.
State:
description: This will be the altitude in meters. You can select a different unit in the entity options if you want.
{% endconfiguration_basic %}

This entity does not have any attributes.

### Sensor - Battery

The Traccar Server integration will create a [sensor](/integrations/sensor) entity for each device registered in Traccar Server to show the remaining battery percentage reported by the Traccar Server.

This entity is disabled by default.

{% configuration_basic %}
Name:
description: The name of the sensor will be set to what you have named it in Traccar Server followed by Battery. If your device is named "Millennium Falcon", this will be "Millennium Falcon Battery".
Entity ID:
description: This will be a slugified version of the name.
Unique ID:
description: This will be the unique ID of the device tracker in Traccar Server followed by `position_attributes.batteryLevel`.
State:
description: This will be the battery percentage (level) as reported by the tracked device, if the device does not have a battery this will be unknown.
{% endconfiguration_basic %}

This entity does not have any attributes.

### Sensor - Geofence

The Traccar Server integration will create a [sensor](/integrations/sensor) entity for each device registered in Traccar Server to show the geofence reported by the Traccar Server.

This entity is disabled by default.

{% configuration_basic %}
Name:
description: The name of the sensor will be set to what you have named it in Traccar Server followed by Geofence. If your device is named "Millennium Falcon", this will be "Millennium Falcon Geofence".
Entity ID:
description: This will be a slugified version of the name.
Unique ID:
description: This will be the unique ID of the device tracker in Traccar Server followed by `geofence_geofence`.
State:
description: This will be geofence that the device is in, if you have overlapping geofences it will show the first one as reported by the Traccar Server.
{% endconfiguration_basic %}

This entity does not have any attributes.

### Sensor - Speed

The Traccar Server integration will create a [sensor](/integrations/sensor) entity for each device registered in Traccar Server to show the speed reported by the Traccar Server.

This entity is disabled by default.

{% configuration_basic %}
Name:
description: The name of the sensor will be set to what you have named it in Traccar Server followed by Speed. If your device is named "Millennium Falcon", this will be "Millennium Falcon Speed".
Entity ID:
description: This will be a slugified version of the name.
Unique ID:
description: This will be the unique ID of the device tracker in Traccar Server followed by `position_speed`.
State:
description: This will be the speed of the device in knots. You can select a different unit in the entity options if you want.
{% endconfiguration_basic %}

This entity does not have any attributes.

### Sensor - Status

The Traccar Server integration will create a [sensor](/integrations/sensor) entity for each device registered in Traccar Server to show the status reported by the Traccar Server.

This entity is disabled by default.

{% configuration_basic %}
Name:
description: The name of the sensor will be set to what you have named it in Traccar Server followed by Status. If your device is named "Millennium Falcon", this will be "Millennium Falcon Status".
Entity ID:
description: This will be a slugified version of the name.
Unique ID:
description: This will be the unique ID of the device tracker in Traccar Server followed by `devcie_status`.
State:
description: This will be one of the following; `offline`, `unknown`, `online`.
{% endconfiguration_basic %}

This entity does not have any attributes.

## Examples

So you set up the integration and it pulled in all your devices. Now what? Below are some examples of what you can do with the data provided by Traccar Server integration.
Expand All @@ -137,7 +240,7 @@ In this section you will find some example automations that you can use to get s

#### Do something when a device enters a geofence

The allows you to do something when the device `device_tracker.millennium_falcon` enters the defined geofence.
The allows you to do something when the device "Millennium Falcon" enters the defined geofence.

{% my blueprint_import badge blueprint_url="https://www.home-assistant.io/blueprints/integrations/traccar_server_device_enter_geofence.yaml" %}

Expand All @@ -146,8 +249,7 @@ The allows you to do something when the device `device_tracker.millennium_falcon
```yaml
trigger:
- platform: state
entity_id: device_tracker.millennium_falcon
attribute: geofence
entity_id: sensor.millennium_falcon_geofence
to: 'Tatooine'
action:
...
Expand All @@ -157,7 +259,7 @@ action:

#### Do something when a device are speeding

The allows you to do something when the device `device_tracker.millennium_falcon` exceeds a defined speed.
The allows you to do something when the device "Millennium Falcon" exceeds a defined speed.

{% my blueprint_import badge blueprint_url="https://www.home-assistant.io/blueprints/integrations/traccar_server_device_speed_limit.yaml" %}

Expand All @@ -166,14 +268,13 @@ The allows you to do something when the device `device_tracker.millennium_falcon
```yaml
trigger:
- platform: numeric_state
entity_id: device_tracker.millennium_falcon
attribute: speed
entity_id: sensor.millennium_falcon_speed
above: 1337
action:
...
```

If you want to include the speed in a notification, you can use the `{{ trigger.to_state.attributes.speed }}` template.
If you want to include the speed in a notification, you can use the `{{ trigger.to_state.state }}` template.

Partial example:

Expand All @@ -183,7 +284,7 @@ trigger:
action:
- service: notify.notify
data:
message: "The current speed of the Millennium falcon is {{ trigger.to_state.attributes.speed }}!"
message: "The current speed of the Millennium falcon is {{ trigger.to_state.state }}!"
```

{% enddetails %}
9 changes: 4 additions & 5 deletions source/blueprints/integrations/traccar_server_device_enter_geofence.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,17 @@ blueprint:
domain: automation
author: ludeeus
homeassistant:
min_version: 2024.2.0
min_version: 1970.1.1 # Placeholder that need replacement but the version is currently not known
input:
devices:
name: Devices
description: The Traccar device(s) trackers you want to act upon
name: Device geofences
description: The Traccar sensor that holds the geofence you want to act upon
selector:
entity:
multiple: true
filter:
integration: "traccar_server"
domain: "device_tracker"
domain: "sensor"
geofence:
name: Geofence
description: The name of the geofence
Expand Down Expand Up @@ -46,7 +46,6 @@ blueprint:
trigger:
- platform: state
entity_id: !input devices
attribute: geofence
to: !input geofence
condition: !input conditions
action: !input actions
Expand Down
7 changes: 3 additions & 4 deletions source/blueprints/integrations/traccar_server_device_speed_limit.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,17 @@ blueprint:
domain: automation
author: ludeeus
homeassistant:
min_version: 2024.2.0
min_version: 1970.1.1 # Placeholder that need replacement but the version is currently not known
input:
devices:
name: Devices
description: The Traccar device(s) trackers you want to act upon
description: The Traccar sensor that holds the speed you want to act upon
selector:
entity:
multiple: true
filter:
integration: "traccar_server"
domain: "device_tracker"
domain: "sensor"
speed:
name: Geofence
description: The speed limit
Expand Down Expand Up @@ -45,7 +45,6 @@ blueprint:
trigger:
- platform: numeric_state
entity_id: !input devices
attribute: speed
above: !input speed
condition: !input conditions
action: !input actions
Expand Down