SwitchBot via hub Bluetooth

localby ALYT

What it adds to a house

adds blinds.

How a person connects it

Method: discover. Choose a capable hub, scan, then select the motors that belong to one curtain. No SwitchBot cloud token is needed.

What it can look for

Yes: “Find Bluetooth devices”.

What stops working when it is disconnected

The commissioned devices are forgotten. Your SwitchBot cloud connection is unchanged.

The descriptor

Connection fields are served for a program at /connectors/switchbot_ble.json.

{
  "source": "built-in",
  "visibility": "public",
  "listed": true,
  "version": "1.0.0",
  "docsUrl": "https://developers.alyt.com/connectors/switchbot_ble",
  "kind": "SWITCHBOT_BLE",
  "name": "SwitchBot via hub Bluetooth",
  "icon": "radio",
  "logo": {
    "url": "/integrations/logos/switchbot.png",
    "color": "#E4262B",
    "ratio": 1,
    "background": "#D33738",
    "inset": 0,
    "scale": 1
  },
  "connectivity": "local",
  "brings": [
    "cover"
  ],
  "connect": {
    "method": "discover",
    "fields": [],
    "help": "Choose a capable hub, scan, then select the motors that belong to one curtain. No SwitchBot cloud token is needed."
  },
  "discovery": {
    "verb": "Find Bluetooth devices",
    "flow": "hub-ble"
  },
  "builtIn": {
    "reason": "its Bluetooth scanner, when the hub reports a supported adapter"
  },
  "disconnect": {
    "consequence": "The commissioned devices are forgotten. Your SwitchBot cloud connection is unchanged."
  },
  "author": {
    "kind": "alyt",
    "name": "ALYT",
    "url": "https://alyt.com"
  }
}

The guide

SwitchBot via hub Bluetooth is a local connector for SwitchBot curtain motors through an ALYT hub’s Bluetooth adapter. It needs no SwitchBot cloud token or secret, works separately from the SWITCHBOT cloud connector, and disconnecting it does not remove any existing cloud connection. Today the supported local path is for Curtain 3 motors, with direct setup from a hub in the same home.

What you need

Use a hub that reports Bluetooth scan support. In the connect flow, choose that hub, Scan for 30 seconds, and select either one motor or two motors that belong to the same curtain. Then Add curtain.

No account fields are required for this connector. The setup is local discovery only.

Management authorization is required to scan, stop a scan, and commission the curtain. Read access to the home is enough to read results.

What gets created

Commissioning creates one endpoint for the selected curtain members, with a name and optional room.

Discovery alone does not create a device. Scan results are only findings until you explicitly add them.

If the same hardware is already present through the cloud connector, local setup can still be kept as a separate endpoint when the commissioning request includes acknowledgeCloudDuplicate.

Supported control

Released local control is for explicitly commissioned single-motor Curtain 3 endpoints. A supported endpoint can expose:

• open
• close
• stop
• position set from 0 closed to 100 open
• attended calibration

For single motors, control is allowed only when the hub ownership, commissioned MAC, accepted firmware revision, fresh Bluetooth report, and current action permission all match. In practice, ordinary motor control depends on the endpoint’s writable descriptor.

Two motors can be registered as one curtain, but paired movement and paired calibration are not currently enabled. For a two-motor endpoint, reported position is representative only. It is not an average and not proof that both sides agree.

If position or battery is missing, treat it as unknown, not zero.

Calibration flow

Calibration is attended. Start by reading calibration/bootstrap. The server decides which actions are allowed; clients should not infer calibration writes from model naming or a calibrated flag.

When the available action set is fluid-v1, the guided sequence is:

1. confirm presence and a clear path
2. confirm physical opening direction
3. confirm the curtain is Fully closed
4. Begin calibration
5. Start opening
6. move continuously left or right, with pauses as needed, until Fully open
7. Start closing
8. move back and pause at Fully closed
9. finish and wait for read checks to confirm the result as Calibration saved

There is no clear or rollback command. Recalibration starts a new sequence. A 60-second firmware watchdog stops unattended movement, and if the client leaves or is hidden, ALYT asks the motor to pause.

Limits and behavior

• No SwitchBot cloud token is needed.
• This connector never removes an existing cloud connection.
• Supported local control is not a blanket promise for all SwitchBot devices or all firmware versions.
• Other SwitchBot Bluetooth findings may appear during scanning but are not necessarily controllable.
• Stop affects only the same motor’s active command.
• A queued or acknowledged command is not the same as completed travel; completion requires fresh matching readback.

If setup or control fails

Check these in order:

1. the selected hub supports Bluetooth scanning
2. the curtain was explicitly commissioned from this hub
3. the device is a supported Curtain 3 motor
4. the endpoint is a single commissioned motor if you expect direct movement control
5. the motor is calibrated before requesting open, close, or position changes
6. the hub has a fresh Bluetooth report from the motor
7. the current firmware/protocol is accepted for this endpoint

A scan can run for up to 30 seconds. Stopping discovery stops the scan only, not curtain movement. Failed scans or commands keep the existing setup and return the real failure reason.