Skip to main content

Services

The integration registers 15 services in the meshcore domain. For event fields, see Events. For examples, see Automation.

Service summary​

ServicePurposeResponseAdmin onlyGoverned lane
send_messageSend a direct message to a contactNoneNoMessages
send_channel_messageSend a message to a channelNoneNoMessages
send_ui_messageSend the text in the UI helpersOptionalNoMessages
execute_commandRun one companion commandOptionalYesMesh commands only
execute_command_uiRun the command in the UI helperOptionalYesMesh commands only
cli_console_clearEmpty the CLI Console transcriptNoneNoNot metered
get_contactsReturn all contactsOnlyNoNot metered
get_discovered_contactReturn one discovered contactOnlyNoNot metered
get_channelsReturn the configured channelsOnlyNoNot metered
traceTrace the route to a contactOnlyNoMessages
add_selected_contactAdd the selected discovered contact to the companionNoneYesNot metered
remove_selected_contactRemove the selected contact from the companionNoneYesNot metered
remove_discovered_contactRemove one discovered contact from Home AssistantNoneNoNot metered
cleanup_unavailable_contactsRemove unavailable contact sensorsNoneNoNot metered
clear_discovered_contactsRemove discovered contacts from Home AssistantNoneNoNot metered

Response: Optional means that the caller can request a response with response_variable or Return response. Only means that a call without response_variable fails.

Admin only: Home Assistant refuses a call from a user who is not an administrator, with the error Unauthorized. Home Assistant permits a call with no user, for example from an automation.

Select the entry​

Each service accepts an optional entry_id: the entry of one companion. If you have one companion, do not set it.

To find the entry_id and the device_id of a companion:

  1. Open Developer Tools > States and filter on node_status.
  2. Copy the entity ID of the Node Status sensor, for example sensor.meshcore_abc123_node_status_mynode.
  3. Open Developer Tools > Template.
  4. Enter {{ config_entry_id('sensor.meshcore_abc123_node_status_mynode') }}. The result is the entry_id.
  5. Enter {{ device_id('sensor.meshcore_abc123_node_status_mynode') }}. The result is the device_id.

With more than one companion, each service selects an entry as follows:

Servicesentry_id not setentry_id not found, or no entry loaded
send_message, send_channel_message, execute_commandThe first connected entry. If no entry is connected, the first loaded entry.Logs an error and does nothing. No event fires.
send_ui_message, execute_command_uiError ambiguous_config_entryError config_entry_not_found
get_contacts, get_discovered_contact, get_channels, traceThe first loaded entryError no_coordinator
cleanup_unavailable_contacts, cli_console_clearAll entriesNothing changes
clear_discovered_contactsThe first loaded entryLogs an error and does nothing
remove_discovered_contactWith pubkey_prefix: the first loaded entry. Without it: error ambiguous_config_entry.Error config_entry_not_found
add_selected_contact, remove_selected_contactError ambiguous_config_entryError config_entry_not_found

See also Two or more companions.

Traffic policy and service calls​

Under the Governed traffic policy, each metered call takes one credit from a lane before it sends. A service call does not wait for credit. If the lane is empty, the call fails at once with this error:

Mesh traffic messages lane is empty; try again in 60 seconds

The number of seconds is the time to the next credit of the lane: a maximum of 180 (flood), 30 (direct) or 60 (messages). See Mesh Traffic Policy: When a lane is empty.

ServiceLaneEvent when the lane is empty
send_message, send_channel_message, send_ui_messageMessagesmeshcore_message_send_failed with reason: traffic_policy
traceMessagesNone
execute_command, execute_command_uiDepends on the command. See CLI Command Reference: Traffic policy.None. The CLI Console does not record the command.

The error stops the automation. To continue, set continue_on_error: true on the action. See Automation.

Installs from 2.x that still use the deprecated Legacy traffic policy do not meter service calls.

Send Message​

Sends a direct message to one contact on the companion.

FieldTypeRequiredDescription
node_idstringOne of node_id or pubkey_prefixThe advertised name of the contact. Exact match, not case-sensitive.
pubkey_prefixstringOne of node_id or pubkey_prefixThe start of the public key of the contact. Not case-sensitive.
messagestringYesThe message text
entry_idstringNoSee Select the entry
  • Set node_id or pubkey_prefix, not both. If you set neither, the call fails and no event fires.
  • The contact must be on the contact list of the companion. A contact that is only discovered does not match.
  • The integration does not check the prefix length, so a short prefix can match a different contact. Use 12 characters.
action: meshcore.send_message
data:
pubkey_prefix: "def456abc012"
message: "Hello from Home Assistant"

The service returns when the companion accepts the message. It does not wait for the acknowledgement (ACK). The ACK wait is 1.2 times the timeout that the companion suggests, or 12 seconds if the companion gives no value. For the events that follow, see Message event order.

If the message does not leave the companion, the integration fires meshcore_message_send_failed. The service call does not fail, except for traffic_policy. For an alert, see Automation: Alert when a send fails.

reasonCause
contact_not_foundNo contact matches node_id or pubkey_prefix
not_connectedThe entry is not connected to its companion
rejectedThe companion refused the message. detail gives the firmware reason.
send_failedAn exception occurred. detail gives the text.
too_longThe text is over 160 bytes. The call also fails.
traffic_policyThe messages lane is empty. The call also fails.
  • The firmware refuses a direct message over 160 bytes (UTF-8) instead of cutting it, so the integration checks the length first and fails the call with the size and the limit. Without that check the radio reports the refusal as a full contact table, which does not name the real cause. A direct message carries no name prefix, so the whole 160 bytes are yours.
  • There is no truncate option here, unlike Send Channel Message: the radio never sends part of an over-long direct message, so cutting one would invent a message the radio would not have sent.

Send Channel Message​

Sends a message to a channel on the companion.

FieldTypeRequiredDescription
channel_idxintegerYesThe channel index (0 or more)
messagestringYesThe message text
scopestringNoA region scope name for this flood, for example myregion or #myregion
truncatebooleanNoCut the text to fit instead of refusing it. Default false.
entry_idstringNoSee Select the entry
action: meshcore.send_channel_message
data:
channel_idx: 1
message: "Hello region"
scope: "myregion"
  • With scope, the integration sets the flood scope on the companion, sends the message, then resets the scope. It also resets the scope after a failed send.

  • If the companion refuses the scope, the integration logs a warning and sends the message without a scope.

  • The firmware sends a maximum of 160 bytes (UTF-8) for the companion name, : and the text together. For a companion name of 11 bytes, the text limit is 147 bytes. An emoji is 4 bytes or more. If the text is longer, the call fails with an error and the companion does not send the message, unless truncate is set.

  • With truncate: true the integration cuts the text to the byte limit and sends it instead of failing. The cut never splits a character, so the result can be a byte or two under the limit. Use it for templated text whose length you cannot predict and whose tail you are willing to lose; leave it off to be told when a message does not fit.

    action: meshcore.send_channel_message
    data:
    channel_idx: 1
    truncate: true
    message: "{{ states('sensor.forecast_summary') }}"

    The firmware cuts over-long channel text on its own and says nothing, so this option puts that cut in the integration, where the length is known and reported. The meshcore_message_sent event carries truncated: true when the text was cut, and message holds the bytes that went out, not what you passed in.

  • A failed send fires meshcore_message_send_failed with message_type: channel. The reason values are the same as for send_message, except contact_not_found. too_long fires only when truncate is off.

Send UI Message​

Sends the message in the UI helper entities of one entry. Use it from a dashboard button.

FieldTypeRequiredDescription
entry_idstringYes, if there is more than one entryThe entry whose helpers the service reads
HelperDefault entity ID (first entry)Value used
Recipient typeselect.meshcore_recipient_typeChannel or Contact
Channelselect.meshcore_channelAttribute channel_idx
Contactselect.meshcore_contactAttribute public_key_prefix
Messagetext.meshcore_messageThe message text

The service finds each helper by its registry identity, so a renamed entity ID continues to work. It calls send_message or send_channel_message, and their rules and events apply. After the send, it clears the message helper and returns {"success": true}. After a traffic policy error, the text stays in the helper.

UI service errors​

send_ui_message and execute_command_ui return an error dictionary when they cannot read the helpers. They do not raise an error. Request a response or read the log (ERROR level) to see the error. Each dictionary has error, message and the extra keys below.

errorCauseExtra keys
config_entry_not_foundentry_id does not exist, or no entry is loadedentry_id, if the call named one
ambiguous_config_entryMore than one entry and no entry_identry_ids
helper_not_foundThe helper is not in the entity registryentry_id, helper, unique_id
helper_state_not_foundThe helper has no stateentry_id, helper, entity_id
helper_state_unavailableThe helper state is unavailable or unknownentry_id, helper, entity_id, state
message_emptyThe message helper is emptyentry_id, entity_id
command_emptyThe command helper is emptyentry_id, entity_id
helper_value_missingThe channel has no channel_idx, or the contact has no public_key_prefixentry_id, helper
invalid_recipient_typeThe recipient type is not Channel or Contactentry_id, recipient_type

Execute Command​

Runs one command on the companion. For the syntax and the command list, see CLI Command Reference.

FieldTypeRequiredDefaultDescription
commandstringYesThe command and its arguments, for example get_bat or set_tx_power 20
record_to_consolebooleanNofalseRecord the command in the CLI Console, and fire meshcore_cli_response
entry_idstringNoSee Select the entry

CAUTION: Do not run a set_* command if you do not know its effect. These commands make permanent changes to the companion configuration.

action: meshcore.execute_command
data:
command: "get_stats_radio"
response_variable: result

A message that you send with send_msg or send_chan_msg fires no message event and makes no logbook entry. Use send_message or send_channel_message instead.

Response shapes​

execute_command_ui and the response field of meshcore_cli_response use the same shapes. Bytes become hex strings.

ResultResponseExample
Event with dataThe event dataget_bat returns {"level": 4123} (mV)
Event without data{"event": <event type>, "command": <name>}{"event": "command_ok", "command": "set_tx_power"}
Error event without data{"error": "rejected", "command": <name>}
Error event with dataThe error data, with "error": "rejected" added{"error": "rejected", "error_code": 2, "code_string": "..."} or {"error": "rejected", "reason": "no_event_received"}
A dictionary (most *_sync commands)The dictionaryreq_status_sync returns the status fields
A list, number or text{"result": <value>}get_path_hash_mode returns {"result": 0}
No result{"error": "no_response", "command": <name>}A *_sync command with no reply

Errors returned as a dictionary:

errorCauseExtra keys
pubkey_prefix_too_shortA contact argument has fewer than 6 characterscommand, argument, detail
not_connectedThe companion is not connected when the integration looks up a contactcommand, argument, detail
contact_not_foundNo contact matches the prefix or the namecommand, argument, detail
invalid_argumentAn argument is not a valid int, float, bool or hex valuecommand, detail
unknown_keywordA keyword argument is not a parameter of the commandcommand, argument
exceptionThe library raised an exception, for example on a lost linkcommand, detail
Incoming message consumption is disabledRetrieve queued incoming messages is off, and you ran get_msgNone

Errors that make the call fail:

  • command_denied: see Denied commands.
  • traffic_deferred: the lane is empty under Governed.
  • Unauthorized: the user is not an administrator.

The service returns no data when the command does not parse, the command does not exist, or no entry is connected. If you request a response, Home Assistant then reports expected a dictionary, but got <class 'NoneType'>. The log gives the cause.

CLI Console​

Set record_to_console: true to record the command and its response. The integration then fires meshcore_cli_response, also when the CLI Console is off. See meshcore_cli_response.

  • The CLI Console sensor, sensor.meshcore_<pk6>_cli_console, shows the last 50 commands. The integration creates it only when you enable Global Settings > Enable CLI Console. Home Assistant hides it by default.
  • The console shows only the commands that you run. It does not show the companion log.

The CLI Console and the event show <redacted> in place of private keys and channel secrets, unless Expose Node Secrets in Events is on. The service response to the caller is not redacted.

For a dashboard card, see Dashboard cards: CLI Console.

Execute Command UI​

Runs the command in the command helper of one entry (text.meshcore_command for the first entry). Then it clears the helper.

FieldTypeRequiredDefaultDescription
entry_idstringYes, if there is more than one entryThe entry whose helper the service reads
record_to_consolebooleanNofalseRecord the command in the CLI Console

The service returns the same response as execute_command, or a UI service error. The CLI Run Command button (button.meshcore_<pk6>_cli_run) calls it with record_to_console: true.

CLI Console Clear​

Empties the CLI Console transcript. Without entry_id, it clears all entries. The CLI Clear Console button (button.meshcore_<pk6>_cli_clear) does the same for its entry.

Query services​

These services return data that the integration already has. Only trace sends a request to the mesh. Each one accepts entry_id.

Get Contacts​

Returns {"contacts": [...]}: the contacts on the companion and the discovered contacts. When a contact is in both lists, the response has the record with the newer lastmod.

FieldDescription
public_keyFull public key, 64 hex characters
pubkey_prefixThe first 12 characters of public_key
added_to_nodetrue if the contact is on the contact list of the companion
adv_nameAdvertised name
type1 client, 2 repeater, 3 room server, 4 sensor
out_path_lenNumber of hops in the route. -1 means no known route.
out_pathThe route as hex, without separators
out_path_hash_modeHash width of each hop: 0 is 1 byte, 1 is 2 bytes, 2 is 3 bytes. -1 means no known route.
flags, last_advert, adv_lat, adv_lon, lastmodOther library fields

On a failure, the response is {"contacts": [], "error": "no_coordinator"} (no entry) or "coordinator_error" (read error).

Get Discovered Contact​

Returns the first discovered contact whose public key starts with pubkey_prefix. Use it in Data only mode, where discovered contacts have no entity. See Contact Management.

  • pubkey_prefix is required, 2 characters minimum. The match is case-sensitive, so use 12 lowercase hex characters.
ResultResponse
Match{"contact": {...}} with the same fields as get_contacts
No match{"contact": null, "error": "not_found", "pubkey_prefix": "def456"}
No entry{"contact": null, "error": "no_coordinator"}
Read error{"contact": null, "error": "coordinator_error"}

Get Channels​

Returns the channels that the integration read from the companion, without a new request:

{"channels": [{"channel_idx": 0, "channel_name": "Public", "shared_secret_present": true}]}

The response omits unused slots and never contains the secret. With no entry, it is {"channels": [], "error": "no_coordinator"}.

Trace​

Traces the route to a contact and returns the hops and the round-trip time.

FieldTypeRequiredDefaultDescription
pubkey_prefixstringYesThe start of the public key. Use 12 lowercase hex characters.
timeoutnumber (seconds)No15The requested wait for the reply, 1 to 120
action: meshcore.trace
data:
pubkey_prefix: "def456abc012"
response_variable: result
  • The contact must be on the companion. A discovered contact, an uppercase prefix or a contact name returns contact_not_on_device.
  • If the contact has no known route, the integration first sends a path discovery and waits 15 to 30 seconds. The full call can then take approximately 90 seconds.
  • The wait for the reply is timeout, a minimum of 5 seconds and a maximum of 60.
  • Routes with hop hashes of 1 to 4 bytes are supported.
  • Under Governed, the trace takes one credit from the messages lane. The path discovery does not take a separate credit.
{"trace": {"hops": 3, "path": [{"hash": "a1", "snr": 6.25}, {"hash": "de", "snr": 4.5}, {"hash": "a1", "snr": 5.0}, {"snr": 7.0}], "round_trip_ms": 3412, "final_snr": 7.0, "tag": 123456789}}
FieldDescription
hopsHops to the contact and back. A contact one repeater away gives 3.
pathOne item for each hop, with hash and snr. The last item is the companion and has only snr.
round_trip_msTime from the send to the reply
final_snrSNR of the reply at the companion
tagThe random tag of this trace

On a failure, the response is {"trace": null, "error": "<code>"}. Only a traffic policy refusal raises an error.

errorCauseExtra keys
no_coordinatorNo entry is loaded, or entry_id is not found
not_connectedThe companion is not connected
contact_not_foundNo contact matches the prefix
contact_not_on_deviceThe contact is not on the companion, or the prefix is uppercase or a name
contact_missing_pubkeyThe contact record has no valid public key
path_discovery_failedThe path discovery was not sent, or its reply was not validreason (no_firmware_ack or malformed_path_response), if known
path_discovery_rejectedThe companion refused the path discoveryreason
path_discovery_timeoutNo path discovery reply
internal_errorThe integration could not build the trace path
send_failedAn exception occurred when the integration sent the trace
unknownThe firmware refused the trace packet
no_response, or a library reason such as no_event_receivedThe companion did not answer the trace send
await_failedAn exception occurred during the wait
timeoutNo trace reply in the wait timeround_trip_ms

Contact services​

These services manage contacts. See Contact Management.

ServiceFieldsDescription
add_selected_contactentry_idAdds the contact in the discovered contact select to the companion
remove_selected_contactentry_idRemoves the contact in the added contact select from the companion
remove_discovered_contactpubkey_prefix (optional), entry_idRemoves one discovered contact and its entity from Home Assistant. The prefix must match one contact. Without pubkey_prefix, it uses the discovered contact select.
cleanup_unavailable_contactsentry_idRemoves the contact binary sensors that are unavailable
clear_discovered_contactsdays_threshold (1 to 365, optional), entry_idRemoves discovered contacts from Home Assistant
  • With more than one entry, add_selected_contact and remove_selected_contact require entry_id. They use the select entity and the companion of that entry.
  • clear_discovered_contacts without days_threshold removes all discovered contacts. It keeps the entities of the contacts on the companion. With days_threshold, the service removes contacts whose lastmod is older than the threshold or missing. It keeps the contacts that Home Assistant added to the companion.

Problems and solutions​

ProblemCauseSolution
expected a dictionary, but got <class 'NoneType'>execute_command returned no dataRead the Home Assistant log
UnauthorizedThe user is not an administratorUse an administrator account, or call the service from an automation

For other problems, see Troubleshooting.