YoLink (YoSmart)

Bring YoLink devices into GEM — leak and freeze sensors, door and motion sensors, smart outlets and switches, water-valve manipulators, sirens and hubs — through the YoLink Open API v2.

YoLink runs its own long-range LoRa radio rather than Wi-Fi or Zigbee, so a single hub covers outbuildings, crawlspaces, well houses and mechanical rooms that Wi-Fi sensors can't reach. That makes it a practical fit for leak detection and freeze monitoring across a property.

Driver name

yolink — set this as the device driver when adding the account in Devices.

One GEM device represents one YoLink account. Each YoLink device on that account becomes a zone.

Prerequisites

• A YoLink account with a hub online and all devices already paired in the YoLink mobile app. This driver does not pair devices — do that in the app first.
• A User Access Credentials pair. In the YoLink app: Settings → Account → Advanced Settings → User Access Credentials → generate. You get a UAID and a Secret Key.
• Outbound HTTPS from the GEM controller to api.yosmart.com.

Cloud service

This is YoLink's cloud API. If the internet link or the YoLink service is down, the account is unreachable. YoLink does publish a local hub API; this driver does not use it.

Setup steps

1. Go to Devices and click Add Device.
2. Choose driver YoLink (YoSmart).
3. Fill in:
   • Client ID (UAID) — the UAID from the app.
   • Client Secret (Secret Key) — the matching secret. Stored encrypted.
   • API Base URL — leave at https://api.yosmart.com unless the account is in the EU service zone.
4. Save. The driver mints an access token and loads the account's device list.
5. Run the get_devices command. It returns every YoLink device with its deviceId, name, type and model.
6. Create one zone per device you want to control or monitor, setting zone.address to the deviceId.

Attribute reference

Device attributes

Attribute	Required	Default	Purpose
client_id	yes	—	The UAID from User Access Credentials.
client_secret	yes	—	The Secret Key. Stored encrypted.
api_base	no	https://api.yosmart.com	Regional host. Use https://api-eu.yosmart.com for EU accounts.
token_url	no	(blank)	Override the token endpoint. Blank means <api_base>/open/yolink/token.
status_interval	no	60000	Milliseconds between polls of every zone.
request_timeout	no	15000	Per-request timeout in milliseconds.

Zone attributes written by the driver

state always carries the device's primary condition. Everything else depends on the device type — the driver publishes whatever numeric, boolean and string fields the device reports, converted to snake_case:

Device type	state values	Typical extra attributes
Switch, Outlet, Manipulator	open / closed	battery, power, delay_on
MultiOutlet	open / closed per outlet	battery, per-outlet power fields
LeakSensor	normal / alert	battery
THSensor	normal / alarm	temperature, humidity, battery
DoorSensor	open / closed	battery
MotionSensor	normal / alert	battery
Siren	on / off	battery

online is written as a boolean whenever the API reports it.

Nested objects the API returns — loraInfo, alarm, schedules, tempLimit — are deliberately not flattened. They are configuration rather than state, and publishing them would churn attribute history on every poll.

Zone address format

zone.address is the YoLink deviceId exactly as get_devices reports it — a 16-character hex string, case-sensitive:

d88b4c0100abcdef

For a multi-outlet power strip, append the 0-based outlet index to address a single outlet:

d88b4c0100abcdef:2

Without an index, a multi-outlet device reports the first outlet's state and control commands apply to the whole strip.

Commands

Command	Arguments	Notes
on / off	address	Maps to open / close. Controllable types only.
toggle	address	Flips based on the last known state.
set_state	address, state	Raw open or close.
alarm_on / alarm_off	address	Sound or silence a siren.
get_devices	—	Lists all devices and refreshes cached per-device tokens.
get_home_info	—	YoLink home id and name.
get_status	—	Polls every zone now.
get_device_state	address	Realtime getState read of one device.
raw_command	address, method, params	Invoke any API method. Escape hatch.

Only these types accept on/off: Switch, Manipulator, Finger, Outlet, MultiOutlet, Siren and WaterMeterController. Anything else returns a clear error rather than silently doing nothing.

How authentication works

There are two tokens, which is the most common source of confusion:

• The account access token rides in the Authorization: Bearer header and is re-minted automatically about two minutes before it expires, and again immediately if the API ever answers 000103.
• The per-device token comes from get_devices and travels inside the request body. If you pair a new YoLink device, run get_devices again so the driver learns its token — the driver also refreshes the list automatically when it is asked about a deviceId it has never seen.

Polling uses fetchState, which reads the cloud's last reported value without waking the node. Device types that don't implement it fall back to getState automatically.

Known limitations

• Reported state, not live state. YoLink sensors are battery LoRa nodes that report on a schedule or on event. Polling reads the cloud's most recent report, so a sensor that checks in every few hours will look stale in between. That is the radio design, not a driver fault. Lowering status_interval does not make a sleeping sensor report sooner.
• No MQTT event stream. YoLink can push device events over MQTT, which would give near-instant leak and door alerts. This driver polls only; MQTT is a worthwhile follow-up and would materially improve alarm latency.
• No local hub API. Cloud only, as noted above.
• Rate limits. The API is rate-limited per account. The driver spaces zone reads by 250 ms and defaults to a 60 s sweep; on large accounts raise status_interval rather than lowering it.
• No pairing, renaming or scheduling. Device provisioning stays in the YoLink app. Thermostat and sprinkler control are not wrapped — reach them with raw_command if needed.

Troubleshooting

Symptom	What to check
could not mint access token	The UAID or Secret Key is wrong or was regenerated. Re-copy both from the app under User Access Credentials.
failed (code 000103)	The bearer token was rejected. The driver re-mints once automatically; a persistent failure means the credentials were revoked.
failed (code 000201)	The device did not answer the cloud — hub offline, device out of range, or a battery node asleep. The zone is marked disconnected and retried next sweep.
failed (code 010203)	That device type does not implement the method. Sensors are read-only; do not send them on/off.
unknown yolink deviceId	zone.address does not match any device on the account. Re-run get_devices and copy the deviceId exactly — it is case-sensitive.
Zone state never populates	Confirm the device reports in the YoLink app first. If it is silent there, it is a pairing or battery problem, not a GEM one.
EU account fails to authenticate	Set api_base to https://api-eu.yosmart.com. If token minting still fails, set token_url to https://api.yosmart.com/open/yolink/token — some EU accounts are still issued credentials by the US host.

Related

• Devices — adding the account.
• Automation Macros — using a leak sensor to close a valve.