Skip to main content

Connect BoatKit to Home Assistant

Connect BoatKit to Home Assistant to make supported live vessel data available as sensors and binary sensors. BoatKit connects directly to the MQTT broker used by Home Assistant and publishes data through MQTT Discovery.

MQTT is a messaging protocol in which a broker routes messages between connected systems. The connection originates from BoatKit, stays read-only with respect to the vessel, and does not pass through BoatKit Cloud. BoatKit accepts no controls or settings changes from Home Assistant.

No Python process, HACS package, or custom BoatKit component is required. BoatKit appears as a device under Home Assistant's built-in MQTT integration.

This connection is not tied to a particular Home Assistant hardware model. It works with a Home Assistant deployment whose MQTT broker is reachable from the dedicated BoatKit device.

Where the publisher runs​

This integration requires the full vessel runtime provided by a dedicated BoatKit device.

You can use Viewer on a phone or tablet to administer that dedicated device. However, a vessel hosted by the mobile app itself does not currently run the Home Assistant publisher.

Before you start​

You need:

  • Home Assistant's built-in MQTT integration configured and connected to a broker. Follow Home Assistant's MQTT integration instructions for current broker and MQTT setup guidance.
  • Network access from the dedicated BoatKit device to that MQTT broker.
  • The broker hostname or IP address and TCP port.
  • The broker's TLS setting.
  • A dedicated MQTT username and password for BoatKit.
  • The MQTT discovery prefix configured in Home Assistant. This is normally homeassistant.

Broker installation and account management vary by Home Assistant deployment and MQTT broker. Use the documentation for your broker when creating the account and its access-control rules.

Grant only the required broker access​

Use a dedicated broker account with the least privilege needed for this integration. BoatKit needs permission to:

  • Publish its discovery configuration beneath the selected discovery prefix.
  • Publish state and availability beneath boatkit/#.
  • Subscribe to Home Assistant's MQTT birth notification so it can restore discovery after Home Assistant restarts. BoatKit listens to homeassistant/status and, when you use a different discovery prefix, that prefix's status topic as well.

The exact access-control syntax depends on your broker.

Connect BoatKit​

  1. Configure Home Assistant's built-in MQTT integration and confirm that it is connected to your broker.

  2. Create the dedicated MQTT account and grant it the permissions described above.

  3. In BoatKit, open Settings.

  4. Select Integrations, then Add Integration.

  5. Select Automation & IoT, then Home Assistant.

  6. Enter the connection settings:

    • MQTT broker host: Enter a hostname or IP address without a URL scheme such as tcp:// and without a path.
    • MQTT broker port: Enter the broker's TCP port.
    • Use TLS: Enable this when the broker expects a TLS-encrypted connection.
    • MQTT username and MQTT password: Enter the dedicated broker credential.
    • Discovery prefix: Enter the same discovery prefix used by Home Assistant. The normal value is homeassistant.

  7. Enable Home Assistant integration.

When Use TLS is enabled, BoatKit verifies the broker certificate against the certificate authorities trusted by the BoatKit device. The certificate must also be valid for the hostname entered in MQTT broker host. BoatKit does not currently provide a custom certificate-authority upload workflow for this integration.

Confirm it is working​

  1. Check the Home Assistant MQTT panel in BoatKit. It should report Connected and show the number of discovered entities.
  2. In Home Assistant, open the MQTT integration and confirm that it shows a BoatKit device.
  3. Choose an entity whose source is currently changing and confirm that its value updates in Home Assistant.

BoatKit groups rapid updates and publishes them at most about twice per second, so a short delay during fast changes is expected.

What BoatKit publishes​

BoatKit exports supported values from its enabled, user-visible categorized source catalog. There is no per-entity export picker in this version.

The export includes:

  • Supported normalized numeric measurements as Home Assistant sensors.
  • Supported time and date values as sensors.
  • Supported on/off values as binary sensors.
  • Friendly source names backed by stable opaque identities, so Home Assistant does not depend on BoatKit's internal source identifiers.

A single BoatKit device publishes at most 512 entities. If more supported values are available, only 512 are included.

This first version intentionally does not publish:

  • Vessel position.
  • Structured values that cannot be represented by the supported sensor types, including gear and autopilot modes.
  • Controls or settings that Home Assistant could change.

Availability, restarts, and removal​

BoatKit publishes online and offline availability for the device. It republishes discovery information when:

  • It connects to the broker.
  • The available source catalog changes.
  • Home Assistant announces that it has restarted.

Disabling or removing the integration stops publication. When BoatKit can still reach the broker, it also sends the discovery removal needed to remove the active BoatKit device document from Home Assistant.

Backups and offline operation​

The MQTT password is stored as a write-only secret on the BoatKit device. It is never returned to Viewer clients and is not included in portable backups. The nonsecret integration settings are backed up.

After restoring a portable backup, enter the MQTT password again before enabling the integration.

The MQTT data path does not pass through BoatKit Cloud. Normal BoatKit device setup and registration still apply. After setup, live publication can continue without an internet connection as long as the BoatKit device, MQTT broker, and Home Assistant remain running and mutually reachable on the network.

Troubleshooting​

BoatKit reports a connection error​

  • Confirm that MQTT broker host contains only the hostname or IP address, without a URL scheme or path.
  • Confirm that MQTT broker port matches the broker's listening port and that Use TLS matches the broker configuration.
  • Re-enter the dedicated MQTT username and password. A broker may report invalid credentials as a general connection failure.
  • Check network routing, name resolution, and firewall rules between the dedicated BoatKit device and the broker. Reaching the broker from your phone or computer does not prove that the BoatKit device can reach it.

The TLS connection fails​

  • Confirm that the broker certificate is valid for the hostname entered in BoatKit.
  • Confirm that the certificate chains to a certificate authority trusted by the BoatKit device.
  • If the certificate is issued for a hostname, use that hostname instead of an IP address.

BoatKit cannot import a custom certificate authority from this settings panel. Use a certificate trusted by the device or configure the broker according to its documentation.

BoatKit is connected but reports zero entities​

BoatKit needs at least one current value of a supported type before it can publish a device with entities.

  • Confirm that live vessel values are visible in BoatKit.
  • Confirm that the relevant sources are enabled and user-visible.
  • Remember that position, gear, autopilot modes, and other unsupported structured values do not create entities.

BoatKit reports entities, but no device appears in Home Assistant​

  • Confirm that Discovery prefix exactly matches the prefix configured by Home Assistant's MQTT integration.
  • Confirm that MQTT discovery is enabled in Home Assistant.
  • Check that the BoatKit broker account can publish both beneath the discovery prefix and beneath boatkit/#.
  • Review the broker logs for denied publications or disconnected clients.

Discovery does not recover after Home Assistant restarts​

Confirm that the BoatKit broker account can subscribe to homeassistant/status. If you use a custom discovery prefix, also allow subscription to that prefix's status topic. BoatKit uses these notifications to republish discovery after Home Assistant returns online.

Entities are unavailable or no longer update​

  • Confirm that BoatKit still reports Connected.
  • Confirm that the BoatKit device, broker, and Home Assistant are all running and can reach one another.
  • Confirm that the underlying value is still live in BoatKit. A supported entity can report unavailable when its source does not currently have a valid value.
  • Allow for the approximately half-second update coalescing interval during rapid changes.

Stale entities remain after an abrupt outage​

An ungraceful outage can prevent BoatKit from sending discovery cleanup before it disconnects.

  1. Restore the connection between the same BoatKit device, broker, and Home Assistant.
  2. Wait for BoatKit to report Connected so it can republish its current discovery information.
  3. If you are retiring the integration, disable or remove it only after the broker is reachable. BoatKit can then send the discovery removal.

Home Assistant is a third-party trademark. This BoatKit integration is not certified or endorsed by Home Assistant.