SharpTools Docs

Appearance

Matter ​

The Matter integration adds devices that are already reachable on your local network through Matter multi-admin setup.

Bridge's Matter support is implemented with matter.js, an open-source TypeScript and JavaScript implementation of the Matter protocol.

Matter Certification

SharpTools Bridge is not Matter certified and does not use the Matter logo or Matter certification marks. References to Matter in these docs describe protocol-level interoperability testing, not product certification by the Connectivity Standards Alliance.

What You'll Need ​

  • A Matter-compatible device already added to another controller, such as Apple Home, Google Home, SmartThings, Amazon Alexa, Home Assistant, or the device manufacturer's app.
  • A multi-admin QR code or setup code from that existing controller.
  • A Bridge installation that can reach the device on the local network.

Setup ​

  1. Open the Bridge admin UI.
  2. Select Add Device.
  3. Choose Matter.
  4. Put the device into multi-admin pairing mode from its existing controller.
  5. Scan the QR code or enter the setup code.
  6. After the device is added, use Devices > Cloud Sync to choose which Bridge devices should sync to SharpTools.

Multi-Admin Pairing ​

To add a Matter device that is already set up elsewhere, generate a new multi-admin pairing code or QR code from the app that currently controls the device. Do not rely on the original setup code from the box unless that controller explicitly tells you to use it for secondary pairing.

Start Bridge First

Open Add Device > Matter in Bridge before generating the code. Many pairing codes expire after a few minutes, so it helps to have Bridge ready before switching to the other app.

  1. Open the Apple Home app.
  2. Select the Matter accessory you want to add to Bridge.
  3. Open the accessory settings.
  4. Select Turn On Pairing Mode.
  5. Select Copy Code, then enter that code in Bridge.

If the code expires or is dismissed, generate a fresh code from Apple Home and try again.

References: Apple Matter accessories, TP-Link multi-admin guide

  1. Open the Google Home app.
  2. Touch and hold the Matter device tile.
  3. Open Settings or the More menu.
  4. Select Linked Matter apps & services.
  5. Select Link apps & services.
  6. Choose Use pairing code or Share with QR code.
  7. Keep the code or QR screen open while adding the device in Bridge.

Reference: Google Home Matter devices

  1. Open the SmartThings app.
  2. Select the Matter device you want to add to Bridge.
  3. Open the More menu or device settings.
  4. Select Share with other services.
  5. Select Share device.
  6. Use the generated QR code or setup code in Bridge.

The generated sharing code is different from the QR code printed on the device.

Reference: SmartThings Matter integration

  1. Open the Alexa app.
  2. Open Devices and select the Matter device you want to add to Bridge.
  3. Open the device settings.
  4. Select Other Assistants and Apps.
  5. Select Add Another to generate a setup code.
  6. Copy the code and enter it in Bridge.

If the code expires, return to the Alexa app and generate a fresh one.

References: Amazon Alexa Matter commissioning, TP-Link multi-admin guide

  1. Open Home Assistant.
  2. Go to Settings > Matter.
  3. Select Devices.
  4. Select the Matter device you want to add to Bridge.
  5. Select Share device, then confirm Share device again.
  6. Scan the generated QR code or enter the sharing code in Bridge.

Home Assistant notes that sharing from Home Assistant does not require pressing a hardware button on the device.

Reference: Home Assistant Matter integration

  1. Open the manufacturer's app for the device or hub.
  2. Open the device settings or the app's Matter settings.
  3. Look for an option like Bind to Matter, Matter pairing, Share device, or Share with other services.
  4. Generate a new Matter setup code or QR code.
  5. Keep the code visible while adding the device in Bridge.

For Matter bridges and hubs, only the device types exposed by that bridge are available through Matter. Some child devices or advanced features may remain available only through the manufacturer's native integration.

References: TP-Link multi-admin guide, Home Assistant Matter bridge notes

Resources and Capabilities ​

Bridge creates one device resource for each supported Matter device or endpoint.

Supported resource types include:

  • On/off, dimmable, color temperature, and color lights.
  • Contact, motion/occupancy, water leak, and water freeze sensors.
  • Thermostats with supported mode, setpoint, operating state, and temperature attributes.

Capabilities are detected from the Matter device type and clusters exposed by the device. Common capabilities include Switch, Switch Level, Light, Color Control, Color Temperature, Contact Sensor, Motion Sensor, Water Sensor, Thermostat Mode, Thermostat Heating Setpoint, Thermostat Cooling Setpoint, Thermostat Operating State, and Temperature Measurement.

Notes and Limitations ​

Current Scope

Bridge does not perform first-time Wi-Fi, Thread, or BLE commissioning for brand-new devices. Add the device to another controller first, then use multi-admin setup to share it with Bridge.

Bridge maintains its own local Matter fabric and stores the local Matter controller data in Bridge storage. Removing a Matter device normally attempts to decommission it from the SharpTools fabric. A force-remove option is available when a device is no longer reachable and only the local Bridge record should be removed.

Troubleshooting ​

If pairing fails, generate a fresh multi-admin code and make sure the Bridge host can reach the device on the same local network. Multi-admin codes are temporary, and some controllers stop advertising the setup code after a short period.

Matter devices can also have a limit on the number of connected services. If a device has already been shared with several apps, remove an unused service from the app that currently controls the device, then try pairing with Bridge again.