Local API Reference

Library: ArmAPIDemo · Version: 1.0.0 · Execution: synchronous, in-memory JavaScript. The source is available as a local download.

ArmAPIDemo.create()

Creates a new, isolated model. Takes no required arguments and returns a frozen API object with the methods below. Freezing the API object prevents replacing its methods; state changes still occur through those methods. Instances do not share pose, gripper, or revision state.

const arm = ArmAPIDemo.create();

arm.getState()

Returns a snapshot with mode, pose, joints, gripper, and revision. The joint object is copied. Changing a returned snapshot does not change the model. Reading state does not increment the revision or notify subscribers.

const state = arm.getState();
console.log(state.mode);     // 'local-demo'
console.log(state.pose);     // 'home'
console.log(state.revision); // 0 on a new model

arm.moveTo(pose)

Parameter: a string exactly equal to 'home', 'reach', or 'lift'. Updates the pose and joint values, preserves gripper state, increments the revision, notifies subscribers, and returns a new snapshot. Even requesting the current pose increments the revision. The return is a local state update, not an animation-completion event.

Errors: throws RangeError for unsupported strings or non-string values. Invalid requests do not modify state or increment the revision.

These values serve this SVG drawing only. No arbitrary-angle method, inverse kinematics, speed control, or collision checking is exposed.

arm.grip(closed)

Parameter: a Boolean. true sets gripper to 'closed'; false sets it to 'open'. Preserves the pose, increments the revision, notifies subscribers, and returns a snapshot. Repeating the current gripper setting still increments the revision.

Errors: throws TypeError for a non-Boolean argument. Strings such as 'true' and numeric values are not coerced. Closing the illustration does not establish that an object was grasped.

arm.reset()

Restores the home pose and open gripper, increments the existing revision, notifies subscribers, and returns a snapshot. It does not set the revision back to zero and does not remove subscribers. Create a new model to start an independent revision sequence.

The page’s Reset button additionally cancels pending page animation steps. Calling this library method alone does not cancel timers created by your own application.

arm.subscribe(listener)

Parameter: a function receiving a snapshot. It is called immediately with the current state and then after each successful mutating method call. Returns an unsubscribe function. Calling that function stops future notifications for the registered listener.

const unsubscribe = arm.subscribe(state => {
  console.log(state.pose, state.gripper, state.revision);
});
arm.moveTo('lift');
unsubscribe();

Errors: a non-function listener throws TypeError. If the immediate first callback throws, registration is removed and the error is rethrown. Errors thrown during later notifications are logged to the console without preventing other subscribers from being notified. Keep listeners observational; synchronous callbacks that repeatedly mutate the same model can create recursive updates.

What this API does not provide.

There are no HTTP endpoints, authentication tokens, robot drivers, hardware connections, joint limits, collision models, persistent storage, or network telemetry. The API also has no claw-round or reward methods. The examples demonstrate the exact local contract; the scope notes explain why an illustration is not a controller.