Skip to main content

Connect Shelly devices

BoatKit can discover compatible Shelly devices and expose their local sensors, inputs, and supported outputs throughout BoatKit. Communication uses an authenticated MQTT broker that BoatKit runs on the vessel network. You do not need a cloud MQTT broker.

Before you begin​

You need:

  • A signed-in, registered BoatKit vessel.
  • Administrator access to BoatKit and the Shelly device.
  • A Shelly device connected to the same trusted Wi-Fi or Ethernet network as the BoatKit host.
  • A dedicated BoatKit device for guided discovery and configuration. App-hosted vessels can use the manual configuration procedure while their local BoatKit runtime remains active.
  • An installation appropriate for the device, circuit, and marine environment.

Check compatibility​

BoatKit currently recognizes Shelly Gen1 topic conventions and the RPC-based conventions used by newer Shelly devices. Shelly Plus Uni is represented in BoatKit's guided-configuration tests, but BoatKit does not yet publish a broader verified list of model, hardware-revision, and firmware combinations.

Treat other Shelly products as compatibility candidates until their exact model and firmware have been confirmed. Advertising MQTT support is not sufficient by itself: MQTT transports messages, but each device family defines its own topics and payloads.

Add the Shelly integration​

  1. Open Settings > Integrations.
  2. Select Automation & IoT in Add Integration.
  3. Find Shelly and select Add.
  4. Turn on Shelly integration if it is not already enabled.
  5. Wait for Shelly Connection to report that BoatKit is listening for Shelly devices.

Enabling Shelly automatically starts BoatKit's shared vessel-local MQTT broker and creates a strong broker password if one is not already set. You do not need to add or enable MQTT separately.

Discover and configure a Shelly automatically​

Guided discovery and MQTT configuration require BoatKit to run on a dedicated device attached directly to the same network as the Shelly.

  1. Power the Shelly and confirm that it has joined the vessel network.
  2. Open the Shelly integration and go to Shelly Discovery.
  3. Select Discover Shelly Devices. BoatKit checks local device advertisements and performs a bounded scan of directly attached networks.
  4. Find the expected device by its name, model, generation, and network address.
  5. Select Configure for BoatKit.
  6. If prompted, enter the password for that Shelly's local web interface. BoatKit uses this password only for the configuration request and does not save it.
  7. Confirm Configure and Restart when a password is required.
  8. Wait for the device to restart and appear under Connected Shelly Devices.

Discovery is read-only. Configuration changes only the selected Shelly's MQTT settings and restarts the device when required by its configuration interface.

note

On Shelly Gen1 firmware, enabling MQTT disables Shelly Cloud. Review that tradeoff before configuring a Gen1 device.

Configure a Shelly manually​

Use manual configuration when the vessel is app-hosted or guided discovery cannot reach the device. Names and layout in the Shelly web interface vary by model and firmware.

  1. Keep the local BoatKit runtime active.
  2. In Shelly Connection, note the broker address and username.
  3. Open Settings > Advanced > MQTT Broker to review the TCP port and set the vessel's broker credentials. The default port is 1883.
  4. Open the Shelly's local web interface and enable its MQTT client.
  5. Enter BoatKit's broker address, TCP port, username, and password.
  6. For a Gen1 device, enable MQTT status publishing. Guided configuration uses a 30-second update period.
  7. For an RPC-based device, enable status notifications, RPC notifications, MQTT RPC, and MQTT control.
  8. Save the device configuration and restart the Shelly if its interface requires it.
  9. Return to the Shelly integration and wait for the device to appear under Connected Shelly Devices.

An app-hosted runtime can provide the broker only while that local runtime remains active. It cannot be relied on as an always-on broker while the host app is suspended.

Select signals and outputs​

Under Connected Shelly Devices, BoatKit groups recognized signals by device and component.

  1. Select the checkbox beside each signal you want to expose.
  2. Give exposed signals recognizable names. A generic name such as Input 0 means the device's local metadata did not provide a more specific component name.
  3. Configure low, high, boolean-state, or availability alerts where appropriate.
  4. Confirm that values update when the physical sensor or input changes.

Enabled numeric and on/off signals become available under the IoT category in gauges, history, and triggers. Alert settings remain active if you later hide a signal from ordinary data views.

Supported writable relay and light outputs use BoatKit's common switch model. The state reported by the Shelly remains authoritative after a command. Do not assume an output changed merely because BoatKit sent the request; wait for BoatKit to display the state reported by the device.

Confirm it is working​

A working installation has these observable results:

  • Shelly Connection reports Listening for Shelly devices with a broker address.
  • The Shelly appears under Connected Shelly Devices and reports Online.
  • Recognized signals show current values and respond to changes at the device.
  • A supported writable output reports its new state after you operate its BoatKit switch.
  • Settings > Advanced > MQTT Broker shows a connected client and an increasing message count while the Shelly publishes updates.

About the shared MQTT broker​

MQTT Broker appears under Settings > Advanced while Shelly or another MQTT-backed IoT integration is enabled. It also remains available if Keep broker enabled independently is on. The page disappears after the last dependent integration and the independent broker setting are both disabled.

The embedded broker:

  • Accepts MQTT 3.1.1 and MQTT 5 clients on eligible vessel-network interfaces.
  • Requires a username and password.
  • Uses TCP port 1883 by default.
  • Shows its listening address, health, connected-client count, and received-message count on the Advanced page.
  • Can remain enabled for generic MQTT clients even when Shelly interpretation is disabled.

Receiving a message on an arbitrary MQTT topic does not create a BoatKit signal. The enabled Shelly integration must recognize the topic and payload before BoatKit can expose the data or control.

Log raw MQTT traffic writes client events, complete topics, and payloads to downloadable BoatKit server logs. Enable it only while collecting diagnostics because payloads may contain sensitive data.

Local operation, credentials, and backups​

After normal BoatKit setup and registration, Shelly communication stays on the vessel network and continues through an ordinary internet outage as long as BoatKit, the local network, and the Shelly remain running. A BoatKit Cloud MQTT broker is not required. Remote access through BoatKit Cloud still depends on an internet connection.

Treat the MQTT username and password as vessel credentials. The password is stored as a vessel secret and is not included in portable configuration backups. Nonsecret MQTT and Shelly settings are portable. Discovery results and live device inventory are replaceable and are rebuilt from devices on the local network.

Troubleshooting​

BoatKit is not listening​

  • Confirm that Shelly integration is enabled.
  • Open Settings > Advanced > MQTT Broker and confirm that both a username and password are set.
  • Check the broker status for an error. BoatKit needs an eligible vessel-network address before it can listen.

No Shelly devices are discovered​

  • Confirm that discovery is running on a dedicated BoatKit device, not an app-hosted vessel.
  • Confirm that BoatKit and the Shelly are on the same directly attached network.
  • Check that the Shelly responds through its local web interface.
  • Run Discover Shelly Devices again after changing networks or device firmware.

A configured device does not connect​

  • Compare the device's broker address, port, username, and password with Settings > Advanced > MQTT Broker.
  • Confirm that the local BoatKit runtime is still active.
  • If the device was restarted, allow it time to reconnect and publish its status.

The broker receives messages but no signals appear​

  • Confirm that the Shelly integration remains enabled.
  • Confirm that the device uses a recognized Gen1 or RPC-based Shelly convention and is publishing its normal announcements and status messages.
  • Remember that an arbitrary MQTT topic is intentionally ignored unless a BoatKit adapter understands it.
  • Temporarily enable Log raw MQTT traffic if support needs complete topic and payload diagnostics, then disable it after collecting the logs.

An output does not change​

  • Confirm that the device is Online and that the output is writable.
  • Check the state reported after the command. If it does not change, BoatKit has not received confirmation that the Shelly accepted or completed the command.
  • Check the device's local interface and installation before retrying the control.
warning

Consumer IoT modules are not automatically suitable for an unprotected marine installation. Use installation-appropriate enclosure, fusing, conductor protection, voltage conversion, electrical isolation, and environmental protection. Follow the device manufacturer's limits and applicable marine electrical requirements.

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