@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_param_default(Igniter.t(), module(), [atom(), ...], term()) ::
  Igniter.t()

Sets a default for a robot parameter in the application config and wires the robot's child spec to load its opts from the application environment.

param_path is the path of the parameter within the robot's params, e.g. [:config, :feetech, :device]. The default is written to config/config.exs as a single leaf under config <app>, <robot_module>, params: [...]. Writing a leaf (rather than the whole opts list) lets independent installers each contribute their own defaults without clobbering one another.

The robot's child spec in the application module is rewritten to {<robot_module>, Application.get_env(<app>, <robot_module>, [])}. If the existing child opts are already a non-literal expression — e.g. a robot_opts() helper call inserted by a composing installer — they're left untouched so that switch logic is preserved.