Skip to main content

Connect MQTT and vessel IoT devices

BoatKit can run an authenticated MQTT broker on the trusted vessel network and translate recognized device messages into normalized sensors, alerts, history, and supported switch controls. The first semantic adapter supports Shelly Gen1 conventions and modern RPC-based Shelly conventions.

Unknown MQTT clients can connect and publish topics, but MQTT does not define the meaning of their payloads. A device needs a BoatKit adapter before its messages become normal BoatKit signals.

Before you begin​

You need:

  • A signed-in, registered BoatKit vessel.
  • A supported MQTT device on the same trusted Wi-Fi or Ethernet network as the BoatKit host.
  • Administrator access to BoatKit and the device being configured.
  • A safe electrical installation appropriate to the device, circuit, and marine environment.

Shelly Plus Uni is a low-voltage sensor and dry-contact module represented in BoatKit's current adapter and guided-configuration tests. Current products such as Shelly 1 Gen4 advertise local MQTT, but confirm BoatKit and device-firmware compatibility before purchase.

Enable the BoatKit broker​

  1. Open Settings > Integrations and add MQTT & IoT.
  2. Confirm the vessel-local username. The default is boatkit.
  3. Set a unique password, or use guided device configuration on a dedicated BoatKit device to generate one.
  4. Keep TCP port 1883 unless the vessel network requires another port.
  5. Enable the integration.
  6. Confirm the panel reports the address where BoatKit is listening.

The broker listens only on eligible vessel-network interfaces, requires username/password authentication, limits client and packet sizes, and does not need a cloud broker. The local path continues during ordinary internet outages after vessel setup and registration.

Configure a Shelly automatically​

Guided discovery and configuration currently require a dedicated BoatKit device.

  1. Put the Shelly and BoatKit device on the same directly attached vessel network.
  2. Open the Shelly Discovery section and run discovery.
  3. Select the expected device by its recognizable name and model.
  4. If the device protects its settings, enter its device password.
  5. Ask BoatKit to configure MQTT. BoatKit writes only the device's MQTT settings and reboots it when the Shelly API says that is required.
  6. Confirm that the device connects to the address shown by BoatKit.

For an app-hosted vessel, or when guided discovery cannot reach the device, configure the Shelly manually using its local web interface and BoatKit's listener address, username, and password. The embedded broker can operate while the app-hosted runtime is active, but mobile suspension prevents it from being an always-on service.

Expose signals and controls​

BoatKit lists recognized signals by device and component. Enable only the signals useful to the vessel, give them recognizable names, and configure low, high, boolean-state, or availability alerts as appropriate.

Supported writable Shelly relay or light outputs appear in BoatKit's common switch model. Reported device state remains authoritative: a command is not considered successful merely because BoatKit published it.

Troubleshooting​

If the broker does not listen, confirm that the integration is enabled, both credentials are set, and the host has an eligible vessel-network address. If a device does not connect, verify its broker address, port, username, password, and local network reachability.

If the device connects but no signals appear, confirm that it is a supported Shelly generation and that it publishes its normal announcements and status topics. Unknown topic conventions are intentionally ignored. Re-run guided discovery on a dedicated device after changing networks or device firmware.

Consumer IoT modules are not automatically marine-rated. Use suitable enclosure, fusing, conductor protection, voltage conversion, isolation, and installation practices for the circuit and environment.

Shelly and MQTT-related marks belong to their respective owners. BoatKit's independent support does not imply certification or endorsement.