@spec add_controller(Igniter.t(), module(), atom(), String.t()) :: Igniter.t()

Adds a controller entry to the robot's controllers do … end section.

code is the full DSL call as a string, e.g.

controller :dynamixel, {BB.Servo.Robotis.Controller, port: ...}

The section is created if it doesn't already exist. Idempotent on name: if a controller with the same name is already present, the igniter is returned unchanged.

@spec add_param_group(Igniter.t(), module(), [atom(), ...], String.t()) :: Igniter.t()

Adds a nested group hierarchy to the robot's parameters do … end section.

group_path is a list of atoms describing the path of nested groups to create, e.g. [:config, :feetech] produces:

group :config do
  group :feetech do
    <body_code>
  end
end

body_code is the contents of the innermost group (typically one or more param ... declarations) as a string.

The parameters section and intermediate groups are created as needed. Idempotent: if the full group path already exists, the body is not added a second time (so manually-edited param contents are preserved).

@spec add_parameter_bridge(Igniter.t(), module(), atom(), String.t()) :: Igniter.t()

Adds a bridge entry to the robot's parameters do … end section.

code is the full DSL call as a string, e.g.

bridge :robotis_bridge, {BB.Servo.Robotis.Bridge, controller: :dynamixel}

The section is created if it doesn't already exist. Idempotent on name.

@spec add_topology_link(Igniter.t(), module(), atom(), String.t()) :: Igniter.t()

Adds a link entry to the robot's topology do … end section.

body_code is the DSL inside the link block as a string, e.g.

visual do
  origin do z(~u(0.1 meter)) end
end

joint :shoulder do
  ...
end

The section is created if it doesn't already exist. Idempotent on name: if a top-level link with the same name is already present, the igniter is returned unchanged.

@spec populate_link(Igniter.t(), module(), [atom(), ...], String.t()) :: Igniter.t()

Populates an existing empty link in the robot's topology with body_code.

link_path is the chain of link names from the topology root down to the leaf to populate, e.g. [:base_link] or [:base_link, :shoulder_link, :upper_arm_link].

Idempotent: if the leaf link already has any DSL entities in its body, the igniter is returned unchanged so user customisations are preserved. If the leaf link is empty, body_code is inserted as its body.

Returns the igniter unchanged if any link in link_path doesn't exist.

@spec robot_module(Igniter.t()) :: module()

Returns the robot module to operate on.

Resolution order:

1. The --robot option from igniter.args.options (parsed module name)
2. {AppPrefix}.Robot (e.g. MyApp.Robot)

Add robot: :string (and ideally aliases: [r: :robot]) to your task's schema to support the --robot flag.

@spec set_robot_opts(Igniter.t(), module(), keyword()) :: Igniter.t()

Ensures the robot's child spec in the application module carries the given opts.

For new robot children, the opts are inserted directly. For existing children, the existing opts are replaced. This is a coarse operation; if multiple installers need to set different keys, the last one to run wins.