Skip to main content

Events

The integration fires eight event types on the Home Assistant event bus. For automation examples, see Automation.

EventWhen it firesIn the logbook
meshcore_messageA message arrives, or the integration logs a message that it sentYes
meshcore_delivery_updateNew delivery data arrives for a message that meshcore_message already announcedNo
meshcore_message_sentThe companion accepts a message from send_message or send_channel_messageNo
meshcore_message_send_failedA message from send_message or send_channel_message did not leave the companionNo
meshcore_raw_eventThe meshcore-py library reports an event from the companionNo
meshcore_cli_responseexecute_command or execute_command_ui completes with record_to_console: trueNo
meshcore_connectedThe link to the companion opens or opens againNo
meshcore_disconnectedThe link to the companion closes or is lostNo

Fields on every event​

Which companion fired the event​

FieldTypeDescription
entry_idstringThe entry (companion) that fired the event. Filter on it when you have more than one companion.
device_idstring or nullThe device registry ID of that companion. It is null before the integration registers the device.

To find these IDs, see Select the entry. On meshcore_cli_response, entry_id is the entry that the service call named. See meshcore_cli_response.

Timestamps​

Eventtimestamp formatExample
meshcore_message, meshcore_delivery_updateISO 8601 string, UTC"2026-10-03T18:08:47.722967+00:00"
meshcore_message_sent, meshcore_message_send_failed, meshcore_cli_responseInteger, Unix seconds1791050927
meshcore_raw_eventFloat, Unix seconds1791050927.7153687

A meshcore_delivery_update carries the timestamp of the message that it updates, not the time of the update.

Secrets in events​

By default, the integration removes node secrets from raw events on the event bus and on MQTT brokers in raw payload mode. It does not forward EventType.PRIVATE_KEY, and it replaces each channel_secret and secret value with "<redacted>". The integration continues to decrypt channel traffic. To forward the real values, enable Global Settings > Expose Node Secrets in Events.

CAUTION: Do not enable Expose Node Secrets in Events on a shared system. Each user of the event bus or the MQTT broker can then read your channel keys.

Message event order​

Use send_id to connect the events of one outgoing message. Only send_message, send_channel_message and send_ui_message fire outgoing events. A message that you send with execute_command (for example send_msg) fires none.

Outgoing direct message​

EventData
meshcore_message_sent (1)progressive: true, ack_received: false
meshcore_message_sent (2)ack_received: true or false. No progressive field.
meshcore_messageoutgoing: true, ack_received
meshcore_delivery_updateprogressive: false, ack_received
  • The timeout is 1.2 times the suggested_timeout of the companion, or 12 seconds if the companion reports no value.
  • If the companion reports no expected ACK code, the integration does not wait, and ack_received is false.
  • The logbook entry appears after the wait ends.

Outgoing channel message​

EventData
meshcore_messageoutgoing: true, collecting: true, repeater_count: 0
meshcore_delivery_update, passes 1 to N-1progressive: true, cumulative rx_log_data
meshcore_delivery_update, pass Nprogressive: false, the final repeater_count
  • Each pass lasts 1 second and fires one update, also when it found no new copies.
  • N is from 4 to 20. N is 4.5 times the airtime of the packet plus 1 second, rounded up. If the integration does not know the radio settings, N is 4.
  • If Home Assistant stops during collection, the integration fires the final update (progressive: false) with the count so far.
  • If the integration cannot correlate the send, meshcore_message carries collecting: false and no update follows.

repeats_observable​

The companion reports a received packet only when it fits in one serial frame (176 bytes). The integration checks the size before the send and sets repeats_observable:

  • true: <sender name>: <text> is 155 bytes or less (UTF-8). The integration can hear relayed copies.
  • false: the text is longer. A repeater_count of 0 then means "unknown", not "not relayed". The Last Message Delivery sensor shows Unconfirmed.

Companion firmware older than 1.16.0 has a frame of 172 bytes. With that firmware, a message can show 0 Repeaters although repeaters relayed it, when <sender name>: <text> is 140 to 155 bytes.

Incoming channel message​

  • The integration matches copies to the message by channel index and sender timestamp. See Messaging: RX_LOG Correlation.
  • In adaptive mode, an update fires only when a check finds new copies. An incoming message never gets an update with progressive: false.
  • When Retrieve queued incoming messages is off, the integration does not send get_msg. See Messaging: Share the companion with a phone.

Incoming direct message​

The integration fires meshcore_message immediately, with no delivery update. A text reply from a repeater to send_cmd also arrives as an incoming direct message.

meshcore_message​

The integration fires meshcore_message one time for each message. This event is the source of the logbook entry. Every variant has domain: "meshcore", entry_id and device_id.

<pk6> is the first 6 hex characters of the companion public key. <node pk6> is the same for the other node.

Incoming direct message fields​

FieldTypePresentDescription
messagestringAlwaysThe message text
sender_namestring or nullAlwaysThe advertised name of the sender. null when the sender is not a contact.
pubkey_prefixstringAlwaysThe public key prefix of the sender (12 hex characters)
receiver_namestringAlwaysAlways "meshcore". It is not the name of your companion.
entity_idstringAlwaysbinary_sensor.meshcore_<pk6>_<node pk6>_messages. The entity exists only for a contact.
timestampstringAlwaysThe time that Home Assistant processed the message
message_typestringAlways"direct"
hop_countintegerAlwaysThe number of hops. 0 means direct reception.
snrfloatWhen the frame has itThe signal-to-noise ratio in dB

Incoming channel message fields​

FieldTypePresentDescription
messagestringAlwaysThe text after the first : . If the text has no : , the full text.
sender_namestringAlwaysThe text before the first : . "Unknown" if the text has no : .
pubkey_prefixstringWhen the sender name matches an added or discovered contactThe first 12 hex characters of the public key of that contact
channelstringAlwaysThe channel name on the companion. If the channel has no name: "public" for channel 0, or the index as a string.
channel_idxintegerAlwaysThe channel index
entity_idstringAlwaysbinary_sensor.meshcore_<pk6>_ch_<channel_idx>_messages
timestampstringAlwaysThe time that Home Assistant processed the message
message_typestringAlways"channel"
hop_countintegerAlwaysThe number of hops. 0 means direct reception.
snrfloatWhen the frame has itThe signal-to-noise ratio in dB
rx_log_datalistWhen the integration matched copiesOne entry for each copy. See rx_log_data entries.

Outgoing direct message fields​

The integration fires this event after the ACK wait ends.

FieldTypeDescription
messagestringThe text that was sent
sender_namestring or nullThe companion name that the entry stored at setup or at the last reconfigure
receiver_namestring or nullThe name of the recipient contact
pubkey_prefixstringThe first 12 hex characters of the public key of the recipient
entity_idstringbinary_sensor.meshcore_<pk6>_<node pk6>_messages
timestampstringThe time that the integration logged the message
outgoingbooleantrue
message_typestring"direct"
send_idstring8 hex characters. The same value is on the meshcore_message_sent events of this send.
ack_receivedbooleantrue when the recipient acknowledged the message before the timeout

Outgoing channel message fields​

The integration fires this event immediately after the companion accepts the message.

FieldTypeDescription
messagestringThe text that was sent
sender_namestring or nullThe companion name that the entry stored at setup or at the last reconfigure
channelstringThe channel name on the companion. "" for a slot with an empty name.
channel_idxintegerThe channel index
entity_idstringbinary_sensor.meshcore_<pk6>_ch_<channel_idx>_messages
timestampstringThe time that the integration logged the message
outgoingbooleantrue
message_typestring"channel"
send_idstring8 hex characters. The same value is on meshcore_message_sent and on each delivery update.
repeats_observablebooleanSee repeats_observable
rx_log_datalistAlways []. Copies arrive in meshcore_delivery_update.
repeater_countintegerAlways 0
progressivebooleanAlways false
collectingbooleantrue when delivery updates will follow

An outgoing message does not carry hop_count or snr.

rx_log_data entries​

Each entry describes one copy of a channel packet that the companion heard.

FieldTypeDescription
channel_idxintegerThe channel index that decrypted the packet
channel_namestringThe channel name on the companion
timestampintegerThe sender timestamp from the decrypted packet (Unix seconds)
textstringThe decrypted text, including the Name: prefix
snrfloatThe signal-to-noise ratio of this copy, in dB
rssiintegerThe received signal strength of this copy, in dBm
path_lenintegerThe number of hops in path
pathstringThe hex hashes of the repeaters that relayed this copy, in order
path_hash_sizeintegerThe bytes for each hop. Split path into parts of path_hash_size * 2 hex characters.
channel_hashstringThe 1-byte channel hash, as hex
route_typeinteger0 TC_FLOOD, 1 FLOOD, 2 DIRECT, 3 TC_DIRECT
route_typenamestringThe name of the route type, for example "TC_FLOOD"
region_scopebooleantrue when route_type is 0 (a region-scoped flood)
flood_scopestring or nullThe matched name from Flood Scope Allowlist, or null

meshcore_delivery_update​

The integration fires meshcore_delivery_update when new delivery data arrives for a message that meshcore_message already announced.

VariantNumber of updatesFinal update
Outgoing channel messageN (4 to 20), one each secondThe last pass has progressive: false
Outgoing direct message1That update has progressive: false
Incoming channel message, adaptive mode only0 to 2None: all updates have progressive: true

Outgoing channel message: the fields are the outgoing channel message fields, without collecting, and with these values:

FieldDescription
rx_log_dataAll copies collected so far (cumulative)
repeater_countThe number of entries in rx_log_data. It does not confirm that other nodes received the message.
progressivetrue on each pass before the last. false on the final update.

Outgoing direct message: the fields are the outgoing direct message fields, plus progressive: false. Use ack_received for the result.

Incoming channel message: the update has entity_id, domain, message_type, sender_name, message, timestamp, rx_log_data (cumulative), repeater_count, progressive: true, entry_id and device_id. It has no send_id. To find the matching meshcore_message, compare entity_id and timestamp.

meshcore_message_sent​

The integration fires meshcore_message_sent when the companion accepts a message. It does not confirm delivery. A direct message fires it two times. To act one time, ignore the event with progressive: true.

FieldTypePresentDescription
messagestringAlwaysThe text that was sent. With truncate, the bytes that went out, not what the service call passed in.
devicestringAlwaysThe entry ID of the companion that sent the message
message_typestringAlways"direct" or "channel"
receiverstring or nullAlwaysDirect: the name of the recipient contact, or null. Channel: "channel_<channel_idx>".
timestampintegerAlwaysUnix seconds when the event fired
send_idstringAlways8 hex characters
contact_public_keystringDirect onlyThe full public key of the recipient
ack_receivedbooleanDirect onlyfalse on the first event. The ACK result on the second event.
progressivebooleanDirect, first event onlytrue
channel_idxintegerChannel onlyThe channel index
send_timestampintegerChannel onlyThe timestamp that the companion used for the packet
scopestring or nullChannel onlyThe flood scope of the service call
truncatedbooleanChannel onlytrue when truncate was set and the text was over the byte budget
entry_id, device_idstringAlwaysSee Which companion fired the event

meshcore_message_send_failed​

The integration fires meshcore_message_send_failed when a message did not leave the companion. The service call does not raise an error, except for traffic_policy and too_long.

FieldTypePresentDescription
reasonstringAlwaysSee the table below
message_typestringAlways"direct" or "channel"
timestampintegerAlwaysUnix seconds
targetstringDirect onlyThe requested recipient, for example node_id 'myclient' or public key 'def456'
channel_idxintegerChannel onlyThe requested channel index
detailstringrejected, send_failed, traffic_policy, too_longThe text from the firmware, the library or the traffic policy. For too_long: the size and the limit in bytes.
entry_id, device_idstringAlwaysSee Which companion fired the event
reasonCauseService call
contact_not_foundNo contact on the companion matches (direct only)Returns
not_connectedThe companion is not connectedReturns
rejectedThe firmware refused the messageReturns
send_failedThe send raised an exceptionReturns
traffic_policyThe messages lane has no credit. See Mesh Traffic Policy.Raises an error
too_longThe text is over the byte budget. Channel: only when truncate is off. See Send Channel Message.Raises an error

No event fires when entry_id does not exist, or when a send_message call has no recipient.

meshcore_raw_event​

The integration fires meshcore_raw_event for each event that the meshcore-py library reports, except PRIVATE_KEY. The meshcore-py source defines each payload.

The recorder stores every one of these events by default. On a busy mesh that is hundreds of thousands of rows in a few days. If you do not use them in automations, exclude them:

recorder:
exclude:
event_types:
- meshcore_raw_event
FieldTypePresentDescription
event_typestringAlwaysThe library event type, for example "EventType.BATTERY"
payloadanyAlwaysThe library payload. Bytes become hex strings. null when serialization failed.
timestampfloatAlwaysUnix seconds when the event fired
serialization_errorstringWhen serialization failedThe error text
entry_id, device_idstringAlwaysSee Which companion fired the event

RX_LOG_DATA additions​

The integration adds two objects to the payload of EventType.RX_LOG_DATA:

FieldPresentDescription
parsedWhen the header can be readheader, path_len, path_hash_size, and for a non-empty path path and path_nodes (one hex string for each hop). Channel packets also have channel_hash.
decryptedOn most packetsThe result of the channel decryption. Use the text only when decrypted.decrypted is true.

When a channel key decrypts the packet, decrypted has decrypted: true, channel_idx, channel_name, timestamp, text, and the parsed route fields. When no key decrypts it, decrypted has only header fields and no decrypted key.

event_type: meshcore_raw_event
data:
event_type: EventType.RX_LOG_DATA
payload:
snr: 9.5
rssi: -71
route_type: 1
route_typename: FLOOD
payload_type: 5
path_len: 1
path_hash_size: 1
path: "cf"
parsed:
header: "15"
path_len: 1
path_hash_size: 1
path: "cf"
path_nodes:
- "cf"
channel_hash: "4a"
decrypted:
decrypted: true
channel_idx: 1
channel_name: "#mychannel"
timestamp: 1791051000
text: "mynode: Test"
path_len: 1
path: "cf"
path_hash_size: 1
channel_hash: "4a"
timestamp: 1791051001.1688693
entry_id: YOUR_ENTRY_ID
device_id: YOUR_DEVICE_ID

meshcore_cli_response​

The integration fires meshcore_cli_response when execute_command or execute_command_ui completes with record_to_console: true. A denied command or a traffic policy refusal fires no event.

FieldTypeDescription
commandstringThe command text
responseobject or nullSee Response shapes. null when the command did not parse, does not exist, or no entry is connected. Private keys and channel secrets show <redacted>, unless Expose Node Secrets in Events is on.
is_errorbooleantrue when response is null or has an error key
entry_idstring or nullThe entry that the service call named. null for a direct execute_command call without entry_id.
resolved_entry_idstring or nullThe entry that ran the command
device_idstring or nullThe device registry ID of the resolved entry
timestampintegerUnix seconds

Connection events​

EventFieldDescription
meshcore_connectedconnection_type"usb", "ble" or "tcp". Fires each time the link opens, also on each reconnect.
meshcore_disconnectedunexpectedtrue when the link is lost. The first reconnect attempt is after approximately 5 seconds. Absent on unload, reload or Home Assistant stop.

Both events carry entry_id and device_id.

Event data examples​

In these examples, the public key of the companion starts with abc123. The public key of myclient starts with def456.

Example: incoming channel message​

event_type: meshcore_message
data:
message: "Good morning"
sender_name: "myclient"
pubkey_prefix: "def456abc012"
channel: "#mychannel"
channel_idx: 1
entity_id: binary_sensor.meshcore_abc123_ch_1_messages
domain: meshcore
timestamp: "2026-10-03T18:08:47.722967+00:00"
message_type: channel
hop_count: 1
snr: 6.25
rx_log_data:
- channel_idx: 1
channel_name: "#mychannel"
timestamp: 1791050927
text: "myclient: Good morning"
snr: 6.25
rssi: -92
path_len: 1
path: "cf"
path_hash_size: 1
channel_hash: "4a"
route_type: 1
route_typename: FLOOD
region_scope: false
flood_scope: null
entry_id: YOUR_ENTRY_ID
device_id: YOUR_DEVICE_ID

Example: final update of an outgoing channel message​

event_type: meshcore_delivery_update
data:
message: "Test"
sender_name: "mynode"
channel: "#mychannel"
channel_idx: 1
entity_id: binary_sensor.meshcore_abc123_ch_1_messages
domain: meshcore
timestamp: "2026-10-03T18:10:00.120000+00:00"
outgoing: true
message_type: channel
send_id: "1a2b3c4d"
repeats_observable: true
rx_log_data:
- channel_idx: 1
channel_name: "#mychannel"
timestamp: 1791051000
text: "mynode: Test"
snr: 9.5
rssi: -71
path_len: 1
path: "cf"
path_hash_size: 1
channel_hash: "4a"
route_type: 1
route_typename: FLOOD
region_scope: false
flood_scope: null
repeater_count: 1
progressive: false
entry_id: YOUR_ENTRY_ID
device_id: YOUR_DEVICE_ID