Motion is an object that exists on a server somewhere. Hosting motions "in the cloud" allow motions to be shared by any online device. Fortunately though, you don't have to worry about the distributed aspect. Instead, just think about motion as a local object in your web browser. As long as you have a reference to this object, your JavaScript code can :

1. query the motion state
2. monitor motion state as it changes in time
3. change the motion
4. react quickly to motion changes

Query simply returns the state of the motion. Query is a local, inexpensive operation. When programming with motions you will query a lot.

var snapshot = motion.query();
var position = snapshot.pos;
var velocity = snapshot.vel;
var acceleration = snapshot.acc;

Here query returnes a snapshot which can be inspected. Alternatively you can use getters for quick access to individual properties. However, if you do, note that the values will be picked from different snapshots.

// WARNING - postion, velocity and acceleration are not drawn from the same snapshot, but 3 sequential snapshots!
var position = motion.pos;
var velocity = motion.vel;
var acceleration = motion.acc;

A simple way to monitor the motion, as it changes in time, is to use the "timeupdate" event. The timeupdate fires periodically every 200ms (5Hz), as long as the motion is not paused (non-zero velocity). If the motion is paused, "timeupdate" pauses too, until the motion is resumed.

motion.on("timeupdate", function(snapshot) {
  // print position from parameter
  console.log(snapshot.pos);
  // print position from motion
  console.log(motion.pos);
  // this === motion
  console.log(this.pos);
})

If the fixed frequency of 5Hz is not appropriate, you may achieve periodic snapshots by the use of setInterval. Additionally you could make this poller sensitive to pause/resume by using the "change" event (see below).

setInterval(function () {
  console.log(motion.query());
}, 50);

Update allows you to control the motion, telling it to change its speed, run backwards, stop, jump to another position, etc.

var sent = motion.update(new_position, new_velocity, new_acceleration);

All parameters are either a number, null or not given (undefined), and the operation is sensitive to the ordering of the parameters. For example, update(1.0) will set the new position to 1.0, and leave the velocity and acceleration unchanged. Update(null, 0, 0) is equivalent to "pause" as it zeroes velocity and acceleration, while keeping the current position. If you never want to use acceleration, just ignore it. Updates to a motion will only succeed if you actually have rights to write to that motion. This depends on the App settings. You may check your credentials with motion.getState().cred;

The return value of Update simply states whether a request has been sent to the remote server or not. In particular, it does NOT indicate that the operations has been performed. Strictly speaking, it doesn't even guarantee that the Update will be performed.

Please note that update is a remote operation. It involves updating an object on a motion server somewhere far-far away. Additionally it involves updating all clients who are currently sharing this motion. For this reason, you should not expect to see the effects of the Update immediately. The Update latency is about 1 RTT (round-trip-time) (less than 0.2 seconds under decent network conditions). Use Update sparingly. For instance, avoid if possible frequent updates of the position in order to create motion, as this defeates the basic motivation for the concept. Instead, use velocity.

Periodic polling may be an inefficient way of detecting changes in a timely manner, as the polling interval must be very small. Instead, you may listen to the "change" event. Note that the "timeupdate" event too will be called when "change" is fired.

motion.on("change", function (snapshot) {
  console.log("motion changed!");  
});

The handler function you now added will be called whenever the MSV changes state. That means that an update has been called. It is not called when for example the position is changed due to the motion having velocity.

Notice also that the handler will be called once, immediately after being attached. This "immediate" event represents the current state of the motion, or the initial state in the perspective of the subscriber. Having both initial state and later state changes pushed through the same handler simplifies programming and encourages a clean data-driven approach. This behaviour is implemented for "timeupdate" as well.

After this brief HOWTO you might want to have a look at the full MotionAPI.