Skip to main content

Sensors and Entities

This page lists every entity that the integration creates. To find the exact IDs on your system, open Developer Tools > States and filter on meshcore.

Placeholders​

The integration changes names to lowercase, changes accented letters to plain letters and replaces spaces and punctuation with _. For example, My Café-Repeater becomes my_cafe_repeater.

PlaceholderMeaningExample
<pk6>First 6 hex characters of the companion public keyabc123
<pk10>First 10 hex characters of the public key of a tracked node or other nodedef456abc0
<pk12>First 12 hex characters of the public key of a contactdef456abc012
<name>Name of the companion, of the tracked node or of the other nodemynode, myrepeater, node_def456
<node pk6>First 6 hex characters of the public key of another nodedef456
<n>LPP channel number of a telemetry value1
<channel_idx>Mesh channel slot on the companion0

A node that you do not track has its advertised name. If the contact has no name, the name is Node <node pk6>. If the node is not in the contact list, the name is Unknown Node <node pk6>.

Devices​

DeviceName formatEntities on the device
CompanionMeshCore <name> (<pk6>)Companion, Self Diagnostics, companion telemetry, contact, message, radio fault and MQTT broker sensors, companion GPS tracker, Firmware update
RepeaterMeshCore Repeater: <name> (<node pk6>)Repeater, route, reliability, Online and neighbor sensors, telemetry sensors, GPS tracker, Refresh firmware version button, Firmware update
ClientMeshCore Client: <name> (<node pk6>)Route, reliability and Online sensors, telemetry sensors, GPS tracker
Other nodeMeshCore Node: <name> (<node pk6>)Telemetry sensors and GPS tracker of a node that you do not track
No device-Select and text helpers, CLI Console sensor, CLI buttons

A room server or sensor node that you add with Add Repeater Station gets a repeater device. When you remove a tracked node, the integration removes its device and entities. The contact sensor of the node stays.

Availability summary​

Entity groupUnavailable when
Companion, Self Diagnostics, route, reliability, Online, message and radio fault sensors, Companion Prefix, Neighbor Count, Discovered Contacts, CLI Console, buttons, firmware updatesThe companion is disconnected (the last coordinator update failed)
Repeater sensorsNo status response in 3 x the update interval (6 h at the default 7200 s). After a restart, until the first status response.
Telemetry sensorsNo telemetry reading in 3 x the update interval (default 6 h). After a restart, until the first reading.
GPS trackersNo GPS reading in 1.5 x the update interval (default 3 h)
Neighbor SNR and Neighbor SeenThe repeater last heard the neighbor 72 h ago or more
Contact sensorsThe contact is not in the contact list of the integration
MQTT broker sensorsThe broker was removed, or the MQTT uploader did not start
Request Rate Limiter, Last Message Delivery, select and text helpersNever

The update interval is Telemetry Refresh Rate (seconds) for a tracked repeater and Update Frequency (seconds) for a tracked client. The companion telemetry sensors and GPS tracker use 7200 s.

Companion sensors​

SensorEntity ID formatState and unitPrecisionSource
Node Statussensor.meshcore_<pk6>_node_status_<name>online or offline-Link state of the companion
Battery Voltagesensor.meshcore_<pk6>_battery_voltage_<name>V3Battery reading of the companion
Battery Percentagesensor.meshcore_<pk6>_battery_percentage_<name>%2Linear scale: 3.0 V is 0 %, 4.2 V is 100 %
Node Countsensor.meshcore_<pk6>_node_count_<name>Number-Contacts added to the companion, plus 1
TX Powersensor.meshcore_<pk6>_tx_power_<name>dBm0Radio settings of the companion
Latitudesensor.meshcore_<pk6>_latitude_<name>Degrees-Advertised position
Longitudesensor.meshcore_<pk6>_longitude_<name>Degrees-Advertised position
Frequencysensor.meshcore_<pk6>_frequency_<name>MHz3Radio settings of the companion
Bandwidthsensor.meshcore_<pk6>_bandwidth_<name>kHz1Radio settings of the companion
Spreading Factorsensor.meshcore_<pk6>_spreading_factor_<name>Number-Radio settings of the companion
Request Rate Limitersensor.meshcore_<pk6>_rate_limiter_tokens_<name>tokens1See Request Rate Limiter
Companion Prefixsensor.meshcore_<pk6>_companion_prefixHex text-See Companion Prefix
Last Message Deliverysensor.meshcore_<pk6>_last_message_delivery_<name>Text-See Last Message Delivery
Discovered Contactssensor.meshcore_<pk6>_discovered_summary_<name>Number-See Discovered Contacts

Example: sensor.meshcore_abc123_battery_voltage_mynode.

Request Rate Limiter​

The state is the credits in the direct lane (0 to 20). For the attributes, see Mesh Traffic Policy. For the state on installs from 2.x that still use the deprecated Legacy policy, see Legacy traffic policy.

Companion Prefix​

The state is the routing prefix of the companion in uppercase hex. Other nodes show this prefix in a route. The path_hash_mode setting of the companion firmware sets the length.

path_hash_modePrefix lengthExample state
0, or not reported1 byteAB
12 bytesABC1
23 bytesABC123

Attributes: public_key, path_hash_mode, prefix_length.

Last Message Delivery​

This sensor shows the result of the last message that this entry sent. For the delivery events, see Events.

StateMessage typeMeaning
Idle-No message sent since the entry loaded
WaitingBothThe companion accepted the message. For a channel message, the integration still listens for repeats.
1 Repeater, 2 Repeaters, and so onChannelThe number of repeats that the companion heard
0 RepeatersChannelNo repeat heard
UnconfirmedChannelNo repeat heard, and the message is too long for the companion to report a repeat
DeliveredDirectThe recipient sent an acknowledgement
UnconfirmedDirectNo acknowledgement arrived
SentDirectThe send ended with no acknowledgement result

Attributes: message_type, last_message, last_send_time. Channel messages add repeater_count, channel, rx_log_data and repeater_details (one item per repeat, with snr, rssi, path_len and path). Direct messages add ack_received and receiver.

Discovered Contacts​

The state is the number of contacts in the discovered list. The integration disables this diagnostic sensor by default. For the attributes, see Contact Management.

Self Diagnostics sensors​

These 14 sensors exist only when Enable Self Diagnostics is set in Global Settings. The integration reads them from the companion with local queries. These queries send nothing over the mesh. Self Diagnostics Interval (seconds) sets the refresh rate (default 300 s). The same setting creates the radio fault sensors.

The entity ID format is sensor.meshcore_<pk6>_<key>_<name>, for example sensor.meshcore_abc123_noise_floor_mynode. The keys are uptime, tx_queue_len, noise_floor, last_rssi, last_snr, tx_airtime, rx_airtime, nb_recv, nb_sent, sent_flood, sent_direct, recv_flood, recv_direct and recv_errors. Each sensor has the unit, precision and state class of the repeater sensor with the same key. tx_airtime matches airtime.

Repeater sensors​

The values come from the status response of each tracked repeater, once per update interval. The entity ID format is sensor.meshcore_<pk10>_<key>_<name>, for example sensor.meshcore_def456abc0_noise_floor_myrepeater.

SensorKeyUnitPrecisionState class
Battery VoltagebatV3Measurement
Battery Percentagebattery_percentage%2Measurement
Uptimeuptimemin (shown as days)-Measurement
Airtimeairtimemin1Total increasing
RX Airtimerx_airtimemin1Total increasing
Airtime Utilizationairtime_utilization%1Measurement
RX Airtime Utilizationrx_airtime_utilization%1Measurement
Messages Sentnb_sent--Total increasing
Messages Receivednb_recv--Total increasing
Sent Flood Messagessent_flood--Total increasing
Sent Direct Messagessent_direct--Total increasing
Received Flood Messagesrecv_flood--Total increasing
Received Direct Messagesrecv_direct--Total increasing
Direct Duplicatesdirect_dups--Total increasing
Flood Duplicatesflood_dups--Total increasing
Full Eventsfull_evts--Total increasing
Receive Errorsrecv_errors--Total increasing
TX Queue Lengthtx_queue_len--Measurement
Noise Floornoise_floordBm0Measurement
Last RSSIlast_rssidBm0Measurement
Last SNRlast_snrdB1Measurement

All repeater sensors have the attribute last_updated. Battery Voltage adds raw_millivolts. Uptime adds human_readable, for example 3d 4h 5m 6s.

Rate and utilization sensors​

These 9 counters also get a rate sensor (unit msg/min, precision 1): nb_sent, nb_recv, sent_flood, sent_direct, recv_flood, recv_direct, direct_dups, flood_dups and recv_errors. The key is the counter key with _rate added, for example sensor.meshcore_def456abc0_nb_recv_rate_myrepeater.

The integration calculates each rate from the last two status responses: the counter change divided by the uptime change, times 60. Utilization is the airtime change divided by the uptime change, times 100. The state is 0 after the first response and after a counter goes down, for example after a repeater restart.

Route and reliability sensors​

The integration creates these 4 sensors for each tracked repeater and tracked client. The entity ID format is sensor.meshcore_<pk10>_<key>_<name>.

SensorKeyStateUnitState class
Routing Pathout_pathThe route as one hex string, with no separators--
Path Lengthout_path_lenThe number of hops on the routehopsMeasurement
Request Successesrequest_successesSuccessful requests to the noderequestsTotal increasing
Request Failuresrequest_failuresFailed requests to the noderequestsTotal increasing
  • Path Length 0 means that the companion hears the node directly. Routing Path is then empty.
  • Path Length unknown means that the companion has no route. Requests to the node are then flood requests.
  • To get the hex characters per hop, divide the length of Routing Path by Path Length.
  • The reliability counters start again at 0 after a Home Assistant restart.

Neighbor sensors​

A repeater with Enable Neighbor Entities set gets the Neighbor Count, Neighbor SNR and Neighbor Seen sensors. For the entity IDs, states and attributes, see Repeater Neighbors.

Telemetry sensors (Cayenne LPP)​

The integration creates a telemetry sensor when a node first sends a reading with a new channel and type. It requests telemetry from each tracked client and from each tracked repeater with Enable Telemetry Polling set. It also requests it from the companion when Enable Self Telemetry is set. A node can also send telemetry with no request.

NodeEntity ID formatExample
Tracked or other nodesensor.meshcore_<pk10>_ch<n>_<type>_<name>sensor.meshcore_def456abc0_ch1_temperature_myrepeater
Multi-value typesensor.meshcore_<pk10>_ch<n>_<type>_<axis>_<name>sensor.meshcore_def456abc0_ch1_accelerometer_x_myrepeater
Companionsensor.meshcore_<pk6>_<type>_ch<n>_<name>sensor.meshcore_abc123_temperature_ch1_mynode

Supported LPP types​

LPP codeType part of the entity IDUnitPrecisionDevice class
0digital_input---
1digital_output---
2analog_inputV2-
3analog_outputV2-
100generic_sensor---
101illuminancelx-Illuminance
102presence---
103temperature°C1Temperature
104humidity%1Humidity
113accelerometer_x, accelerometer_y, accelerometer_zG3-
115barometerhPa1Atmospheric pressure
116voltageV2Voltage
117currentA (shown as mA)1Current
118frequencyHz0Frequency
120percentage%0-
121altitudem1Distance
122loadkg3Weight
125concentrationppm0-
128powerW0Power
130distancem3Distance
131energykWh3Energy
132direction°0-
133time---
134gyrometer_x, gyrometer_y, gyrometer_z°/s2-
135color_red, color_green, color_blue---
142switch---
  • Presence, Digital Input, Digital Output and Switch are numeric sensors, not binary sensors.
  • GPS (LPP code 136) creates a GPS tracker, not a sensor.
  • An LPP type that is not in the table creates a generic sensor.
  • A tracked client that sends a voltage on channel 1 gets 2 sensors in place of the voltage sensor: sensor.meshcore_<pk10>_ch1_battery_voltage_<name> (V) and sensor.meshcore_<pk10>_ch1_battery_<name>. The second sensor has the device class Battery and uses the 3.0 V to 4.2 V scale.

Attributes: channel, lpp_type, pubkey_prefix, node_type (root, repeater, client, contact or unknown), node_name, field (multi-value types only), last_updated, raw_value.

Binary sensors​

Binary sensorEntity ID formatDeviceStatesWhen created
Contactbinary_sensor.meshcore_<adv name>_<pk12>_contactCompanionfresh, stale, discoveredSee Contact sensors
Onlinebinary_sensor.meshcore_<pk10>_online_<name>Tracked nodeon, off, unknownFor each tracked repeater and tracked client
Channel messagesbinary_sensor.meshcore_<pk6>_ch_<channel_idx>_messagesCompanionActiveAt the first message on the channel
Contact messagesbinary_sensor.meshcore_<pk6>_<node pk6>_messagesCompanionActiveAt the first direct message with the contact
MQTT brokerbinary_sensor.meshcore_<pk6>_mqtt_broker_<number>_connectionCompanionon, offFor each MQTT broker that the uploader loads
Radio faultbinary_sensor.meshcore_<pk6>_<fault key>_<name>Companionon, off, unknownWhen Enable Self Diagnostics is set

Contact sensors​

Example: binary_sensor.meshcore_myrepeater_def456abc012_contact. For the states, the attributes and the Contact Discovery Mode rules, see Contact Management.

Online sensors​

The Online sensor shows if a tracked node answers the requests of the integration. Node Status shows only the link between Home Assistant and the companion.

StateCondition
onThe last successful request is in the staleness window
offThe last successful request is older than the staleness window
unknownNo successful request since Home Assistant started

The staleness window is 2.5 x the update interval of the node, with a minimum interval of 300 s. At the default of 7200 s, the window is 5 h.

Attributes: last_successful_request, update_interval, staleness_window (seconds).

Message sensors​

The state is always Active. The logbook uses these sensors to show the messages. See Messaging.

  • Channel messages: attribute channel_index.
  • Contact messages: attribute public_key (12-character prefix). A sender that is not a contact gets no sensor.

Radio fault sensors​

These 3 sensors decode the errors value of the companion. The firmware clears a flag only when the companion restarts. Thus on means that the fault occurred at least one time since the companion started. The state is unknown until the first Self Diagnostics reading.

Fault keyNameMeaning
err_pool_fullRadio Fault: Packet Pool ExhaustedThe packet pool was full, and the companion dropped a packet
err_cad_timeoutRadio Fault: CAD TimeoutChannel Activity Detection stayed busy for too long
err_rx_timeoutRadio Fault: RX-Start TimeoutThe companion did not go back into receive mode

MQTT broker sensors​

Attributes: broker_number, server. The sensors follow broker changes without a reload. See MQTT.

GPS trackers​

The integration creates a GPS tracker when a node first sends a GPS reading (LPP code 136).

NodeEntity ID format
Tracked or other nodedevice_tracker.meshcore_<pk10>_gps_<name>
Companiondevice_tracker.meshcore_<pk6>_gps_<name>

Companion telemetry sensors and the companion GPS tracker from before 3.0 keep their old entity IDs. See Upgrade to 3.0.

The location accuracy is 10 m when the reading gives no accuracy. Attributes: pubkey_prefix, node_type, node_name, altitude (when present), last_updated.

Buttons​

ButtonEntity ID formatDeviceWhen created
Refresh firmware versionbutton.meshcore_<pk10>_refresh_firmwareRepeaterFor each tracked repeater
CLI Run Commandbutton.meshcore_<pk6>_cli_runNone (hidden)When Enable CLI Console is set
CLI Clear Consolebutton.meshcore_<pk6>_cli_clearNone (hidden)When Enable CLI Console is set

A press of Refresh firmware version costs one credit. If the lane has no credit, the press fails with an error.

Firmware updates​

UpdateEntity ID formatDeviceWhen created
Firmwareupdate.meshcore_<pk6>_firmwareCompanionAlways
Firmwareupdate.meshcore_<pk10>_firmwareRepeaterFor each tracked repeater

Each update entity compares the firmware that the node reported with the newest stable release of the MeshCore firmware for the role of the node:

NodeInstalled version fromRelease line
CompanionThe device query at connectcompanion-v*
Tracked repeaterThe Refresh firmware version button, or the version kept in the device registryrepeater-v*
Tracked room serverThe same as a repeaterroom-server-v*

The integration checks the releases on GitHub every 12 hours. One check serves all config entries. Pre-releases and drafts are ignored. The check uses no mesh airtime.

The entities only report an update. They have no install action, because MeshCore nodes are flashed over USB or with the web flasher. Release notes shows the notes of the release, and the entity links to the release page.

If the node has not reported a version, the entity has no latest version and does not show an update. Press Refresh firmware version to read the version of a repeater.

CLI Console sensor​

ItemValue
Entity IDsensor.meshcore_<pk6>_cli_console (no device, hidden)
When createdWhen Enable CLI Console is set in Global Settings
StateThe number of command and response pairs in the transcript (last 50 kept)
Attributeshistory, transcript, last_command, last_response, last_is_error, command_count, max_lines

The recorder does not store the transcript attributes, because a command can contain a password. For a card, see Dashboard cards.

Select and text helpers​

These helpers have no device, are hidden by default and are always available.

EntityOptions or valueAttributes
select.meshcore_recipient_typeChannel, Contact-
select.meshcore_channelOne option per channel slot, as <channel name> (<index>)channel_idx
select.meshcore_contactAdded contacts that are not repeaters, as <name> (<pk12>)public_key_prefix, public_key, contact_name
select.meshcore_discovered_contactDiscovered contacts, as <name> (<pk12>)pubkey_prefix, public_key, contact_name
select.meshcore_added_contactAll added contacts, as <name> (<pk12>)pubkey_prefix, public_key, contact_name
text.meshcore_messageThe message text, 200 characters maximum-
text.meshcore_commandThe command text, 255 characters maximum-

With two entries, the helpers of the second entry get a suffix such as _2. See Two or more companions.

Usage examples​

This template sensor counts the MeshCore battery sensors below 20 %. It ignores unknown and unavailable.

template:
- sensor:
- name: "Mesh low battery nodes"
unique_id: mesh_low_battery_nodes
state: >
{% set ns = namespace(count=0) %}
{% for id in integration_entities('meshcore') | select('match', 'sensor[.]') %}
{% if state_attr(id, 'device_class') == 'battery'
and states(id) | is_number
and states(id) | float < 20 %}
{% set ns.count = ns.count + 1 %}
{% endif %}
{% endfor %}
{{ ns.count }}