DocsSound, sensors and files

Sensors and the watch

A scene can read numbers from the world: your heart rate from a watch, your steps, the light in the room, anything a device can send. A glow can beat with your pulse, a sky can fill as your steps add up. This page is about using those readings in a scene. Getting them to your computer is set up in Motion Player (see Sensors in the app).

How a reading gets to a scene

Readings travel through Motion Hub's relay:

1. Your watch, phone or script sends a reading, with a token from Motion Hub that's allowed to write that sensor.
2. The relay passes it on at once. It keeps only the latest reading of each sensor, as it came (an encrypted one stays encrypted), so a wallpaper that starts listening has one straight away, and a history only if you ask for one.
3. Motion listens with a token that's allowed to read it, which Motion Player makes with your Hub account, takes from someone's share or you paste in, and hands the latest reading of each sensor to the scenes that read it.

The readings come to your computer only. Motion listens only while a scene on screen reads a sensor, and only for the sensors that scene reads (and while its Settings are open, for the sensors your library's scenes read, to show them). A token can only touch the sensors you ticked when you made it, and you can revoke it on the Hub at any time.

What there is to read

Each sensor has an id. These are the ones Motion Hub knows:

Most are numbers. Some are yes or no (charging, presence), some are words, and a custom one can be anything.

Connecting a watch

The watch gets its token from Motion on your phone: Settings, Open Sensors, Add a watch. The token's keys go with it, so its readings are encrypted from the start. The watch has the steps.

Anything that can call a web address can send readings too: a shortcut on your phone, a home automation system, a few lines of script. Make a token under Tokens on Motion Hub that can write those sensors, and the Hub shows the exact command to try. Readings sent this way aren't encrypted, so Motion takes them only once Accept unencrypted readings is on for that token (see Encrypted readings).

Then, on the computer, give Motion Player a token that can read those sensors: Settings, Sensors, then Connect my phone or watch when the app is signed in to the Hub, or paste one under Or paste a token. One for each device or person is easiest to keep track of. Sensors in the app goes through this step by step.

Encrypted readings

Readings are encrypted on the device that sends them and opened only by devices that have the token's keys. The token only signs in. The app that made the token (Motion Player, or Motion for Android) makes its keys, and neither the relay nor Motion Hub can read them. (An older token gets its keys the first time you press Copy its keys by hand for it in Motion Player, or Make keys on this phone on Android.) Your approved Motion apps pass them to each other on their own, locked for each device (Your devices' keys), and you can also give them by hand: Copy its keys by hand, under a token's Advanced: its token and keys in Motion Player, shows them, and the phone gives them to the watch when it sends it the token. The relay passes readings on and sees which sensor each is of, and Motion Hub sees that they came, but neither can read them.

New tokens work this way from the start. Because the Hub can't read them, it shows encrypted where it would show the latest values, and history and webhooks are off. If you want those for a token, turn on Let the Hub read this token's readings on its page, and turn off Encrypt readings on the devices that send with it.

Motion takes unencrypted readings, and readings from older senders, only while Accept unencrypted readings is on for the token in Motion's Sensors settings. It's off unless you turn it on, so only devices with the token's keys can reach your wallpaper. A reading older than the newest one Motion already has never replaces it.

A share link can't open a token's encrypted readings by itself: it needs keys made for it by Motion Player that made the token. So share with Share my sensors in Motion Player. A link it makes comes with its keys after it, which open only the link's sensors until it ends, and a share with someone's Motion Hub account passes the keys between your two Motions, locked so the Hub can't open them, once you've typed the code theirs shows (Sharing your sensors).

When a share ends, Motion makes new keys for the token and passes them, through Motion Hub, to the devices that send with it and to the shares that remain. Whoever's share ended can still read what came before, but nothing after. A device that was off at the time picks the new keys up when it next connects.

The watch, through your phone

Motion for Wear OS sends your watch's heart rate, steps, movement and battery. When your phone is nearby and has Motion installed, the watch hands its readings to the phone over the watch's own link to it, and the phone passes them to the relay. That saves the watch's battery: its Bluetooth link to the phone costs far less than keeping its own Wi-Fi or mobile connection open. When the phone is out of reach, the watch sends over its own connection, and it goes back to the phone when it can. The phone can't read the readings either; they're encrypted on the watch.

The phone only does this while the watch is sending, with a small notification while it does. Readings go once a second, and heart rate every two seconds while it holds steady. Readings every on the watch sends everything less often, every 5 or 30 seconds, which saves more battery.

To give the watch a token, open Motion on the phone, go to Settings, Open Sensors, Add a watch: a watch in reach is offered it straight away, and keeps it once you press Add on the watch. A watch out of reach takes it by the code it shows, typed on the phone under Another watch, by a code; the Hub's website can't add a watch, as it never has the keys that encrypt its readings. The watch has the steps.

The Sensors tab

A scene lists the sensors it listens to on Studio's Sensors tab, beside Layer and Scene at the top of the inspector. Listen to a sensor adds one, and each has:

1. Sensor: which one. The list has every sensor Motion knows, and Custom… at its end takes an id of your own, such as custom.mood.
2. Readings from and to: the reading that counts as nothing and the one that counts as everything, for whatever follows it. For a heart rate, 40 to 180 works. For steps, 0 to your day's goal.
3. Smoothing: how many seconds it takes to follow a new reading, so a jumpy sensor doesn't make the scene twitch.
4. Before a reading: where it rests until the first reading arrives.
5. Share as: the name the scene knows it by. It starts as the sensor's id, and pulse may read better than heart_rate. Names are letters, digits and _, starting with a letter, and each sensor in a scene has its own. Rename one and the scene's settings and text that use it follow.
6. Simulate: made-up readings in Studio's preview, even when a token feeds it (see below).

Beside its name is its reading now. Used by lists what uses it: the settings that follow it, in amber, and the text that shows it. Click one to pick its layer. Remove stops listening to it.

The scene hears only the sensors on its Sensors tab. Each is read from the token Motion Player reads from for the scene (Whose sensors it reads).

Showing a reading

A Text and clock layer shows a reading wherever its words have the sensor's name in braces: {pulse} bpm shows 72 bpm. Under its words, Insert a reading has a chip for each of the scene's sensors, with its reading now. Click one to put it where the cursor is. Decimals is how many decimal places it's shown with, and Before a reading is what the layer shows until a reading comes (left empty, a dash stands in for the reading).

Driving a setting with it

Any setting on any layer can follow one of the scene's sensors:

1. Click ∿ beside the setting.
2. Under Follows, pick A sensor.
3. Under Sensor, pick it by the name it's shared as.
4. High gives is the value the setting reaches when the reading is at the top of its range. At the bottom, the setting sits at the value you gave it.
5. Answers is how it gets there: Straight, Gently or Quickly.

So for glow orbs that pulse faster with your heart: listen to heart_rate on the Sensors tab, then click ∿ beside the orbs' Layer speed (under Layer) and have it follow that sensor. The Driven by tab on each layer lists what follows a sensor.

Whose sensors it reads

A scene never carries a token, on Motion Hub or anywhere else. Whoever uses it chooses whose sensors it reads in Motion Player, on the scene's page under Whose sensors: their own, or those of someone who shares with them. So you can share a scene that shows "your heart rate", and it shows the heart rate of whoever puts it on their desktop.

Studio's preview reads from the same token Motion Player reads from for the scene, so the preview hears what the wallpaper will. With no token kept, the preview simulates the readings instead.

Making a sensor wallpaper without the sensors

You don't need a watch, or anyone's token, to make a scene that reads sensors. Studio can simulate them: it makes up believable readings for every sensor the scene listens to, with the right units and ranges, and feeds them to the preview exactly as real ones arrive. The scene can't tell the difference, so what you see is what the wallpaper will do with real readings.

The preview simulates every sensor when no token is kept in Settings › Sensors, which is the usual case when you start. When you do have tokens, turn on a sensor's Simulate on the Sensors tab, or Simulate all, to simulate it anyway. The wallpaper still hears the token.

Simulate sensors

On the Sensors tab, a simulated sensor shows a graph of the last 45 seconds and the next 15, and the pattern it follows. Simulate sensors, under the list, has the clock they all follow. While the preview plays, it says Simulated sensors in its corner, so you never take the readings for real ones.

Each sensor follows a pattern:

• Steady: one Value that doesn't change.
• Activity loop: rest, a walk, a run and a cool-down, over the Activity loop's length (a minute unless you change it). Heart rate climbs and falls with it, steps and calories count up faster as the pace picks up, motion shakes harder, blood oxygen dips, and a location goes round a park. It's the easiest way to see a heart-rate scene go through its whole range.
• Wave: smoothly from Low to High and back, once a Period.
• Random walk: wanders between Low and High, the way room temperature or light drifts.
• Keyframed: a timeline of values you set. Type them as seconds: value (0: 60, 15: 120, 30: 60), or click the graph to put a key there and Shift+click to take the nearest away. It plays round from the last key.

Speed makes a pattern go faster or slower than the clock. A custom sensor (custom.mood) can read words instead of a number: type them, separated by commas, and its value picks one.

The clock### The clock

The simulation runs on its own clock while the Sensors tab and the preview are open:

• Pause stops it, so the readings hold still while you adjust a layer; Go on starts it again.
• Drag the slider to scrub through the activity loop and see how the scene looks at any moment.
• Rest, Walk, Run and Cool-down jump straight to that part of the loop.
• Spike heart rate (and the same for any number) makes that sensor shoot up now and settle over half a minute, to check a scene's reaction to a sudden change.

Readings arrive at the rate the real sensor sends them: heart rate four times a second, battery every five seconds, motion as fast as the preview takes it.

Where it's kept

The simulation is saved with the scene, so it's there the next time you open the scene. It's yours as the author: a wallpaper never plays it, Motion Player never shows it, and Motion Hub never gets it as readings.

When you publish, Motion Hub draws the scene's picture with your simulation instead of its usual sample readings. Press Use for Motion Hub's picture to pick the moment it shows, say the middle of the run, so your heart-rate wallpaper looks its best in its preview.

Sensors in scripts

scene.sensor gives the latest reading of one of the scene's sensors, by the name it's shared as or its id, as { value, at } (at in milliseconds), or null before there is one. scene.on with "sensor" runs a function on each new reading; scene.onSensor does the same for one sensor, and gives back what stops it. scene.sensorAge says how long since a sensor's last reading, in seconds (null before one): a way to tell that a watch has gone quiet. scene.sensors lists the scene's sensors, each with the name it's shared as.

scene.onSensor("pulse", (bpm: number) => scene.animate("Pulse", "speed", bpm / 60, 1));
scene.every(10, () => scene.show("Asleep", (scene.sensorAge("pulse") ?? 999) > 60));

scene.on("sensor", (id, value: number, at, name) => {
    if (name === "pulse")
        scene.animate("Glow", "speed", value / 60, 1);
});

In visual scripts, Get Sensor Reading gives a sensor's value (Result), when it came (When) and whether there's one yet (Has One). Give its Sensor input the name the sensor is shared as, or its id. On Sensor Reading acts on each new reading of one sensor, Sensor Age says how long since the last, and Get Sensors lists them.

A scene only hears the sensors on its Sensors tab.

When nothing arrives

Text that shows a reading shows a dash (or its own Before a reading) until the first reading, and the settings that follow it sit at the sensor's Before a reading. If it stays that way:

• Check the scene's page in Motion Player: Whose sensors must have a token picked.
• For someone's shared sensors: their row in Settings › Sensors says if they've stopped sharing or the share has run out. Their encrypted readings open once their Motion has sent you the keys, which it does after they type the code your Motion shows on the share's row.
• Check the token on Motion Hub: it must be able to read that sensor, and not be revoked or run out. Settings, Sensors in Motion Player shows each token's state, and under Readings the latest value of each sensor and how long ago it came.
• Check the sender: the token's page on the Hub shows when a device last sent.

Last changed 2 November 2026. Something wrong here? Tell us.