Reference

Every public module, class and call of the anvil package, generated from its docstrings.

anvil

The Anvil SDK: a workcell's arms, grippers, cameras and control loop, programmed from Python.

Import the module you use and name things through it: import anvil.control, then anvil.control.Runtime; or from anvil.control import Runtime. Each module loads only what it needs on import, and import anvil on its own loads nothing but the exceptions below.

• anvil.workcell: what is bolted down — robots, arms, grippers, cameras, keep-out boxes — and the shipped presets.
• anvil.kinematics: chains, forward kinematics, IK and poses.
• anvil.control: the controllers, their commands and tunings, and the anvil.control.Runtime that runs them.
• anvil.hw: the drives and the sim's, and the readiness check.
• anvil.sim: the sim's world, a robot standing in a scene with MuJoCo standing in for its drives.
• anvil.camera, anvil.recorder: cameras, and episodes with their compression and export.
• anvil.apps: the teleop apps and episode replay.

Every exception the SDK raises is an anvil.Error, and also the builtin a Python caller would expect: a refused value is an anvil.InvalidArgumentError, a ValueError; a call that could not be carried out an anvil.OperationError, a RuntimeError; a bug in the SDK itself an anvil.PanicError. Where a caller can act on why a call failed, the anvil.OperationError is a subclass naming it: anvil.NotFoundError, a FileNotFoundError; anvil.BusyError; anvil.TimedOutError, a TimeoutError; anvil.UnreachableError, a ConnectionError. These live here because any module's calls raise them; a failure only one module's calls meet is named in that module, like anvil.control.HwFaultError. The one other exception is Python's own TypeError, for an argument of the wrong type, such as a string where an anvil.kinematics.Pose goes: it names the parameter and the type it takes.

What the SDK logs goes to Python's logging at info and above, on loggers under anvil, each named for the part of the stack that logged, so logging.getLogger("anvil") reaches them all. A record carries the thread, file and line that logged it, and is handled on that thread, never inside a tick of the control loop, so a slow handler cannot delay one. The SDK sets up no handler: an application's logging decides where records go, and one that sets none sees warnings and errors on stderr.

The SDK reports to Anvil: each anvil.PanicError as a crash report, and how the SDK is used, a robot started and stopped or an episode recorded, as events naming nothing in the episode, under the serial of a machine Anvil provisioned or an ID made at random for any other. ANVIL_TELEMETRY=0 in the environment turns both off; set it before importing any anvil module, as each reads it once, when it loads.

Classes:

Name	Description
BusyError	Raised when what the call needs is held by another program or another call: a bus, a camera, an episode.
Error	Raised by any SDK call that fails: the base of every exception the SDK raises, so catching it catches them all.
InvalidArgumentError	Raised when a call refuses a value it was given: out of range, the wrong length, or a file not of the right form.
NotFoundError	Raised when a file, directory or device the call names is not there: a path, a camera, a CAN interface.
OperationError	Raised when a call took its arguments but could not carry them out, for a reason no subclass names.
PanicError	Raised when the SDK hit a bug of its own, in this call or in an earlier one on the same object.
TimedOutError	Raised when what the call waited on did not happen in the time it was given.
UnreachableError	Raised when a peer the call needs did not answer: a motor silent on its bus, no sim server at the address.

Attributes:

Name	Type	Description
__all__
__version__		The release this SDK is, e.g. 2.0.0-a5: its libraries' version, as the installed package carries it.

__all__ module-attribute

__all__ = [
    "BusyError",
    "Error",
    "InvalidArgumentError",
    "NotFoundError",
    "OperationError",
    "PanicError",
    "TimedOutError",
    "UnreachableError",
]

__version__ module-attribute

__version__ = '2.0.0-b4'

The release this SDK is, e.g. 2.0.0-a5: its libraries' version, as the installed package carries it.

BusyError

Bases: OperationError

Raised when what the call needs is held by another program or another call: a bus, a camera, an episode.

Nothing was taken. Call again once the holder lets go: close the object that holds it, or stop the program that does; an episode is held until its recording stops.

Error

Bases: Exception

Raised by any SDK call that fails: the base of every exception the SDK raises, so catching it catches them all.

Each subclass is also the builtin a Python caller expects for its kind, so except ValueError catches a refused value and except FileNotFoundError a missing file, as anywhere else. Its message, str(error), says what failed and the value it saw; like any Python exception it has no message attribute.

InvalidArgumentError

Bases: Error, ValueError

Raised when a call refuses a value it was given: out of range, the wrong length, or a file not of the right form.

The call stopped before acting on it, so the object it was made on is as it was: correct the value and call again. It is a ValueError.

NotFoundError

NotFoundError(message: str)

Bases: OperationError, FileNotFoundError

Raised when a file, directory or device the call names is not there: a path, a camera, a CAN interface.

Nothing was opened: fix the path, or plug the device in, and call again. It is a FileNotFoundError, its errno errno.ENOENT and its filename None: the path is in the message.

Takes message as its text, str(error), and sets the errno a FileNotFoundError the OS raised would.

OperationError

Bases: Error, RuntimeError

Raised when a call took its arguments but could not carry them out, for a reason no subclass names.

The subclasses name the reasons a caller can act on: anvil.NotFoundError, anvil.BusyError, anvil.TimedOutError, anvil.UnreachableError, anvil.control.HwFaultError, anvil.control.StoppedShortError and anvil.control.PreemptedError. This class itself is also what any call on an object raises once it was closed, or once an anvil.control.Runtime took it over; make a new one to go on. It is a RuntimeError.

PanicError

Bases: Error, RuntimeError

Raised when the SDK hit a bug of its own, in this call or in an earlier one on the same object.

The object the call was made on is good only for closing: close it, make a new one, and send Anvil the message. A crash report goes to Anvil as well, unless ANVIL_TELEMETRY=0. Any call can raise it, so no call lists it. It is a RuntimeError.

TimedOutError

TimedOutError(message: str)

Bases: OperationError, TimeoutError

Raised when what the call waited on did not happen in the time it was given.

Only the wait ended: what it waited on may still be under way, as a trajectory goes on playing past its timeout_s. It is a TimeoutError, its errno errno.ETIMEDOUT.

Takes message as its text, str(error), and sets the errno a TimeoutError the OS raised would.

UnreachableError

Bases: OperationError, ConnectionError

Raised when a peer the call needs did not answer: a motor silent on its bus, no sim server at the address.

A call that was opening something opened nothing; on an object already open, such as a anvil.hw.SimHw whose sim went away, the object answers nothing more, so build a new one. Check that it is powered, wired and running, for a sim that anvil-robotics sim is up at that address, and call again. It is a ConnectionError, its errno None, since no one errno covers a silent motor and a refused connection alike.