BB

The DSL extension for describing robot properties and topologies.

topology

Robot topology

Nested DSLs

link
- inertial
  - origin
  - inertia
- visual
  - box
  - cylinder
  - sphere
  - capsule
  - mesh
  - material
    - color
    - texture
  - origin
- collision
  - origin
  - box
  - cylinder
  - sphere
  - capsule
  - mesh
- sensor
joint
- origin
- axis
- dynamics
- limit
- sensor
- actuator

topology.link

link name

A kinematic link (ie solid body).

Nested DSLs

inertial
- origin
- inertia
visual
- box
- cylinder
- sphere
- capsule
- mesh
- material
  - color
  - texture
- origin
collision
- origin
- box
- cylinder
- sphere
- capsule
- mesh
sensor

Arguments

Name	Type	Default	Docs
`name`	`atom`		The name of the link

topology.link.inertial

A link's mass, position of it's center of mass and it's central inertia properties

Options

Name	Type	Default	Docs
`mass`	`any`		The mass of the link

topology.link.inertial.origin

Specifies where the link's center of mass is located, relative to the link's reference frame

Options

Name	Type	Default	Docs
`roll`	`any`	`Cldr.Unit.new!(:degree, 0)`	rotation around the `x` axis
`pitch`	`any`	`Cldr.Unit.new!(:degree, 0)`	rotation around the `y` axis
`yaw`	`any`	`Cldr.Unit.new!(:degree, 0)`	rotation around the `z` axis
`x`	`any`	`Cldr.Unit.new!(:meter, 0)`	translation along the `x` axis
`y`	`any`	`Cldr.Unit.new!(:meter, 0)`	translation along the `y` axis
`z`	`any`	`Cldr.Unit.new!(:meter, 0)`	translation along the `z` axis

Introspection

Target: BB.Dsl.Origin

topology.link.inertial.inertia

How the link resists rotational motion.

Options

Name	Type	Docs
`ixx`	`any`	Resistance to rotation around the x-axis
`iyy`	`any`	Resistance to rotation around the y-axis
`izz`	`any`	Resistance to rotation around the z-axis
`ixy`	`any`	Coupling between the x and y axes
`ixz`	`any`	Coupling between the x and z axes
`iyz`	`any`	Coupling between the y and z axes

Introspection

Target: BB.Dsl.Inertia

Introspection

Target: BB.Dsl.Inertial

topology.link.visual

Visual attributes for a link.

Nested DSLs

box
cylinder
sphere
capsule
mesh
material
- color
- texture
origin

topology.link.visual.box

Box geometry

Options

Name	Type	Docs
`x`	`any`	The length of the X axis side
`y`	`any`	The length of the Y axis side
`z`	`any`	The length of the Z axis side

Introspection

Target: BB.Dsl.Box

topology.link.visual.cylinder

A cylindrical geometry

The origin of the cylinder is the center.

Options

Name	Type	Default	Docs
`radius`	`any`		The distance from the center to the circumference
`height`	`any`		The height of the cylinder

Introspection

Target: BB.Dsl.Cylinder

topology.link.visual.sphere

A spherical geometry

The origin of the sphere is its center.

Options

Name	Type	Default	Docs
`radius`	`any`		The distance from the center of the sphere to your edge

Introspection

Target: BB.Dsl.Sphere

topology.link.visual.capsule

A capsule geometry (cylinder with hemispherical caps).

The origin of the capsule is the centre of the cylindrical portion. The height is the distance between the centres of the hemispherical caps. Total extent is height + 2 * radius.

Options

Name	Type	Default	Docs
`radius`	`any`		The radius of the capsule (cylinder and hemispherical caps)
`height`	`any`		The height of the cylindrical portion (between cap centres)

Introspection

Target: BB.Dsl.Capsule

topology.link.visual.mesh

A mesh object specified by a filename

Options

Name	Type	Default	Docs
`filename`	`String.t`		The path to the 3D model
`scale`	`number`	`1`	A scale factor for the mest

Introspection

Target: BB.Dsl.Mesh

topology.link.visual.material

The material of the visual element

Nested DSLs

color
texture

Options

Name	Type	Default	Docs
`name`	`atom`		The name of the material

topology.link.visual.material.color

The color of the meterial

Options

Name	Type	Default	Docs
`red`	`any`		The red element of the color
`green`	`any`		The green element of the color
`blue`	`any`		The blue element of the color
`alpha`	`any`	`1`	The alpha element of the color

Introspection

Target: BB.Dsl.Color

topology.link.visual.material.texture

A texture to apply to the material

Options

Name	Type	Default	Docs
`filename`	`String.t`		The image file to use

Introspection

Target: BB.Dsl.Texture

Introspection

Target: BB.Dsl.Material

topology.link.visual.origin

The refrence frame of the visual element with respect to the reference frame of the link

Options

Name	Type	Default	Docs
`roll`	`any`	`Cldr.Unit.new!(:degree, 0)`	rotation around the `x` axis
`pitch`	`any`	`Cldr.Unit.new!(:degree, 0)`	rotation around the `y` axis
`yaw`	`any`	`Cldr.Unit.new!(:degree, 0)`	rotation around the `z` axis
`x`	`any`	`Cldr.Unit.new!(:meter, 0)`	translation along the `x` axis
`y`	`any`	`Cldr.Unit.new!(:meter, 0)`	translation along the `y` axis
`z`	`any`	`Cldr.Unit.new!(:meter, 0)`	translation along the `z` axis

Introspection

Target: BB.Dsl.Origin

Introspection

Target: BB.Dsl.Visual

topology.link.collision

The collision properties of a link.

Nested DSLs

origin
box
cylinder
sphere
capsule
mesh

Options

Name	Type	Default	Docs
`name`	`atom`		An optional name of the link geometry

topology.link.collision.origin

The refrence frame of the collision element, relative to the reference frame of the link

Options

Name	Type	Default	Docs
`roll`	`any`	`Cldr.Unit.new!(:degree, 0)`	rotation around the `x` axis
`pitch`	`any`	`Cldr.Unit.new!(:degree, 0)`	rotation around the `y` axis
`yaw`	`any`	`Cldr.Unit.new!(:degree, 0)`	rotation around the `z` axis
`x`	`any`	`Cldr.Unit.new!(:meter, 0)`	translation along the `x` axis
`y`	`any`	`Cldr.Unit.new!(:meter, 0)`	translation along the `y` axis
`z`	`any`	`Cldr.Unit.new!(:meter, 0)`	translation along the `z` axis

Introspection

Target: BB.Dsl.Origin

topology.link.collision.box

Box geometry

Options

Name	Type	Docs
`x`	`any`	The length of the X axis side
`y`	`any`	The length of the Y axis side
`z`	`any`	The length of the Z axis side

Introspection

Target: BB.Dsl.Box

topology.link.collision.cylinder

A cylindrical geometry

The origin of the cylinder is the center.

Options

Name	Type	Default	Docs
`radius`	`any`		The distance from the center to the circumference
`height`	`any`		The height of the cylinder

Introspection

Target: BB.Dsl.Cylinder

topology.link.collision.sphere

A spherical geometry

The origin of the sphere is its center.

Options

Name	Type	Default	Docs
`radius`	`any`		The distance from the center of the sphere to your edge

Introspection

Target: BB.Dsl.Sphere

topology.link.collision.capsule

A capsule geometry (cylinder with hemispherical caps).

The origin of the capsule is the centre of the cylindrical portion. The height is the distance between the centres of the hemispherical caps. Total extent is height + 2 * radius.

Options

Name	Type	Default	Docs
`radius`	`any`		The radius of the capsule (cylinder and hemispherical caps)
`height`	`any`		The height of the cylindrical portion (between cap centres)

Introspection

Target: BB.Dsl.Capsule

topology.link.collision.mesh

A mesh object specified by a filename

Options

Name	Type	Default	Docs
`filename`	`String.t`		The path to the 3D model
`scale`	`number`	`1`	A scale factor for the mest

Introspection

Target: BB.Dsl.Mesh

Introspection

Target: BB.Dsl.Collision

topology.link.sensor

sensor name, child_spec

A sensor attached to the robot, a link, or a joint.

Arguments

Name	Type	Default	Docs
`name`	`atom`		A unique name for the sensor
`child_spec`	`module \| {module, keyword}`		The child specification for the sensor process. Either a module or `{module, keyword_list}`

Introspection

Target: BB.Dsl.Sensor

Introspection

Target: BB.Dsl.Link

topology.joint

joint name

A kinematic joint between a parent link and a child link.

Nested DSLs

origin
axis
dynamics
limit
sensor
actuator

Arguments

Name	Type	Default	Docs
`name`	`atom`		A unique name for the joint

Options

Name	Type	Default	Docs
`type`	`:revolute \| :continuous \| :prismatic \| :fixed \| :floating \| :planar`		Specifies the type of joint

topology.joint.origin

This is the transform from the parent link to the child link. The joint is located at the origin of the child link, as shown in the figure above

Options

Name	Type	Default	Docs
`roll`	`any`	`Cldr.Unit.new!(:degree, 0)`	rotation around the `x` axis
`pitch`	`any`	`Cldr.Unit.new!(:degree, 0)`	rotation around the `y` axis
`yaw`	`any`	`Cldr.Unit.new!(:degree, 0)`	rotation around the `z` axis
`x`	`any`	`Cldr.Unit.new!(:meter, 0)`	translation along the `x` axis
`y`	`any`	`Cldr.Unit.new!(:meter, 0)`	translation along the `y` axis
`z`	`any`	`Cldr.Unit.new!(:meter, 0)`	translation along the `z` axis

Introspection

Target: BB.Dsl.Origin

topology.joint.axis

The joint axis specified in the joint frame. This is the axis of rotation for revolute joints, the axis of translation for prismatic joints, and the surface normal for planar joints. The axis is specified in the joint frame of reference. Fixed and floating joints do not use the axis field

Options

Name	Type	Default	Docs
`roll`	`any`	`Cldr.Unit.new!(:degree, 0)`	rotation around the X axis
`pitch`	`any`	`Cldr.Unit.new!(:degree, 0)`	rotation around the Y axis
`yaw`	`any`	`Cldr.Unit.new!(:degree, 0)`	rotation around the Z axis

Introspection

Target: BB.Dsl.Axis

topology.joint.dynamics

An element specifying physical properties of the joint. These values are used to specify modeling properties of the joint, particularly useful for simulation.

Options

Name	Type	Default	Docs
`damping`	`any`		The physical damping value of the joint
`friction`	`any`		The physical static friction value of the joint

Introspection

Target: BB.Dsl.Dynamics

topology.joint.limit

Limits applied to joint movement

Options

Name	Type	Docs
`effort`	`any`	The maximum effort - both positive and negative - that can be commanded to the joint
`velocity`	`any`	Maximum velocity - both positive and negative - that can be commanded to the joint
`lower`	`any`	The lower joint limit
`upper`	`any`	The upper joint limit

Introspection

Target: BB.Dsl.Limit

topology.joint.sensor

sensor name, child_spec

A sensor attached to the robot, a link, or a joint.

Arguments

Name	Type	Default	Docs
`name`	`atom`		A unique name for the sensor
`child_spec`	`module \| {module, keyword}`		The child specification for the sensor process. Either a module or `{module, keyword_list}`

Introspection

Target: BB.Dsl.Sensor

topology.joint.actuator

actuator name, child_spec

An actuator attached to a joint.

Arguments

Name	Type	Default	Docs
`name`	`atom`		A unique name for the actuator
`child_spec`	`module \| {module, keyword}`		The child specification for the actuator process. Either a module or `{module, keyword_list}`

Introspection

Target: BB.Dsl.Actuator

Introspection

Target: BB.Dsl.Joint

settings

System-wide settings

Options

Name	Type	Default	Docs
`name`	`atom`		The name of the robot, defaults to the name of the defining module
`registry_module`	`module`	`Registry`	The registry module to use
`registry_options`	`keyword`		Options passed to Registry.start_link/1. Defaults to `[partitions: System.schedulers_online()]` at runtime.
`supervisor_module`	`module`	`Supervisor`	The supervisor module to use
`parameter_store`	`module \| {module, keyword}`		Optional parameter persistence backend. Use a module or `{Module, opts}` tuple.
`auto_disarm_on_error`	`boolean`	`true`	Automatically disarm the robot when a hardware error is reported. Defaults to true.

sensors

Robot-level sensors

Nested DSLs

sensor

sensors.sensor

sensor name, child_spec

A sensor attached to the robot, a link, or a joint.

Arguments

Name	Type	Default	Docs
`name`	`atom`		A unique name for the sensor
`child_spec`	`module \| {module, keyword}`		The child specification for the sensor process. Either a module or `{module, keyword_list}`

Introspection

Target: BB.Dsl.Sensor

controllers

Robot-level controllers

Nested DSLs

controller

controllers.controller

controller name, child_spec

A controller process at the robot level.

Arguments

Name	Type	Default	Docs
`name`	`atom`		A unique name for the controller
`child_spec`	`module \| {module, keyword}`		The child specification for the controller process. Either a module or `{module, keyword_list}`

Options

Name	Type	Default	Docs
`simulation`	`:omit \| :mock \| :start`	`:omit`	Behaviour in simulation mode: :omit (don't start), :mock (start no-op mock), :start (start real controller)

Introspection

Target: BB.Dsl.Controller

commands

Robot commands with Goal → Feedback → Result semantics

Nested DSLs

category
command
- argument

commands.category

category name

A command category for grouping commands with concurrent execution limits.

Categories define logical groups of commands (e.g., :motion, :sensing, :auxiliary) with configurable concurrency limits. Commands in different categories can run concurrently, while commands in the same category are limited to the category's concurrency_limit.

Arguments

Name	Type	Default	Docs
`name`	`atom`		A unique name for the category

Options

Name	Type	Default	Docs
`doc`	`String.t`		Documentation describing this category
`concurrency_limit`	`pos_integer`	`1`	Maximum number of commands in this category that can run concurrently

Introspection

Target: BB.Dsl.Category

commands.command

command name

A command that can be executed on the robot.

Commands follow the Goal → Feedback → Result pattern and integrate with the robot's state machine to control when they can run.

Nested DSLs

argument

Arguments

Name	Type	Default	Docs
`name`	`atom`		A unique name for the command

Options

Name	Type	Default	Docs
`handler`	`module \| {module, keyword}`		The handler module implementing the `BB.Command` behaviour. Either a module or `{module, keyword_list}` for parameterised options
`timeout`	`pos_integer \| :infinity`	`:infinity`	Timeout for command execution in milliseconds
`allowed_states`	`atom \| list(atom)`	`[:idle]`	Robot states in which this command can run. Use `:*` for all states (except `:disarmed`). Use `:disarmed` explicitly if the command should run when disarmed.
`category`	`atom`	`:default`	The command category for concurrency control. Commands in the same category are limited by that category's concurrency_limit.
`cancel`	`atom \| list(atom)`	`[]`	Categories of commands this command can cancel when starting. Use `:*` to cancel all running commands, or a list of specific categories. Empty list (default) means the command will error if its category is at capacity.

commands.command.argument

argument name, type

An argument for the command.

Arguments

Name	Type	Default	Docs
`name`	`atom`		A unique name for the argument
`type`	`any`		The type of the argument

Options

Name	Type	Default	Docs
`required`	`boolean`	`false`	Whether this argument is required
`default`	`any`		Default value if not provided
`doc`	`String.t`		Documentation for the argument

Introspection

Target: BB.Dsl.Command.Argument

Introspection

Target: BB.Dsl.Command

parameters

Runtime-adjustable parameters for the robot.

Parameters provide a way to configure robot behaviour at runtime without recompilation. They support validation, change notifications via PubSub, and optional persistence.

Example

parameters do group :motion do param :max_linear_speed, type: :float, default: 1.0, min: 0.0, max: 10.0, doc: "Max velocity in m/s" param :max_angular_speed, type: :float, default: 0.5 end

group :safety do param :collision_distance, type: :float, default: 0.3 end end

Nested DSLs

group
- param
param
bridge

parameters.group

group name

A group of runtime-adjustable parameters.

Nested DSLs

param

Arguments

Name	Type	Default	Docs
`name`	`atom`		A unique name for the parameter group

Options

Name	Type	Default	Docs
`doc`	`String.t`		Documentation for the parameter group

parameters.group.param

param name

A runtime-adjustable parameter.

Arguments

Name	Type	Default	Docs
`name`	`atom`		A unique name for the parameter

Options

Name	Type	Docs
`type`	`any`	The parameter value type (:float, :integer, :boolean, :string, :atom, or {:unit, unit_type})
`default`	`any`	Default value for the parameter
`min`	`number`	Minimum value for numeric parameters
`max`	`number`	Maximum value for numeric parameters
`doc`	`String.t`	Documentation for the parameter

Introspection

Target: BB.Dsl.Param

Introspection

Target: BB.Dsl.ParamGroup

parameters.param

param name

A runtime-adjustable parameter.

Arguments

Name	Type	Default	Docs
`name`	`atom`		A unique name for the parameter

Options

Name	Type	Docs
`type`	`any`	The parameter value type (:float, :integer, :boolean, :string, :atom, or {:unit, unit_type})
`default`	`any`	Default value for the parameter
`min`	`number`	Minimum value for numeric parameters
`max`	`number`	Maximum value for numeric parameters
`doc`	`String.t`	Documentation for the parameter

Introspection

Target: BB.Dsl.Param

parameters.bridge

bridge name, child_spec

A parameter protocol bridge for remote access.

Bridges expose robot parameters to remote clients (GCS, web UI, etc.) and receive parameter updates from them. They implement BB.Bridge.

Example

parameters do bridge :mavlink, {BBMavLink.ParameterBridge, conn: "/dev/ttyACM0"} bridge :phoenix, {BBPhoenix.ParameterBridge, url: "ws://gcs.local/socket"} end

Arguments

Name	Type	Default	Docs
`name`	`atom`		A unique name for the bridge
`child_spec`	`module \| {module, keyword}`		The child specification for the bridge process. Either a module or `{module, keyword_list}`

Options

Name	Type	Default	Docs
`simulation`	`:omit \| :mock \| :start`	`:omit`	Behaviour in simulation mode: :omit (don't start), :mock (start no-op mock), :start (start real bridge)

Introspection

Target: BB.Dsl.Bridge

states

Custom operational states for the robot.

The built-in :idle state is always available. Define additional states here and use commands to transition between them. Commands can specify which states they're allowed to run in via allowed_states.

Nested DSLs

state

Options

Name	Type	Default	Docs
`initial_state`	`atom`	`:idle`	The initial operational state when the robot starts

states.state

state name

A custom operational state for the robot.

States define the operational context the robot can be in. Commands specify which states they can run in via allowed_states, and can transition to new states via next_state: in their result.

Arguments

Name	Type	Default	Docs
`name`	`atom`		A unique name for the state

Options

Name	Type	Default	Docs
`doc`	`String.t`		Documentation describing this state

Introspection

Target: BB.Dsl.State

← Previous Page Telemetry Events Reference