@spec available?(opts()) :: boolean()

Checks whether the firmware is actually ready — not merely accepting TCP.

Ready means the command socket answers a GET_STATE request AND the report stream produces a parseable frame. Returns false on any failure.

@spec await_report(:gen_tcp.socket(), binary(), pos_integer(), (report() ->
                                                            as_boolean(term()))) ::
  {:ok, report(), binary()} | {:error, term()}

Reads report frames until fun returns a truthy value or timeout elapses.

Useful for observing motion: "wait until J1 is within 0.02 rad of the target". Returns {:ok, report, rest} with the first matching frame, or {:error, :timeout} with the deadline exceeded.

Examples

{:ok, report_socket} = Simulator.connect_report()
{:ok, _first, rest} = Simulator.read_report(report_socket)

{:ok, _frame, _rest} =
  Simulator.await_report(report_socket, rest, 20_000, fn r ->
    abs(hd(r.angles) - target) < 0.02
  end)

@spec command(:gen_tcp.socket(), binary(), timeout()) ::
  {:ok, {byte(), byte(), binary()}, binary()} | {:more} | {:error, term()}

Sends a command frame and returns the parsed response.

Drains stale responses first, then sends frame (built with BB.Ufactory.Protocol) and parses the reply. Returns {:ok, {register, status, params}, rest}, {:more} on a truncated response, or {:error, reason}.

Examples

{:ok, cmd} = Simulator.connect_command()

{:ok, {0x0F, _status, <<error_code, _warn>>}, _rest} =
  Simulator.command(cmd, Protocol.cmd_get_error(0))

@spec connect_command(opts()) :: {:ok, :gen_tcp.socket()} | {:error, term()}

Opens a passive TCP connection to the command socket (port 502).

@spec connect_report(opts()) :: {:ok, :gen_tcp.socket()} | {:error, term()}

Opens a passive TCP connection to the real-time report stream (port 30003).

Read frames with read_report/2 or await_report/4.

@spec current_state(opts()) :: {:ok, report()} | {:error, term()}

Snapshots the arm's current state from a fresh report connection.

Opens a new connection so the frame reflects now rather than a stale buffer backlog. Returns {:ok, report} with the full report map (:angles, :pose, :state, :mode, …) or {:error, reason}.

@spec drain(:gen_tcp.socket()) :: :ok

Drains any unread responses from a command socket's receive buffer.

Fire-and-forget frames (moves, RS485 writes, prepare_arm/2) generate responses nobody reads; drain before a request/response exchange so the next recv reads its own reply. command/3 does this automatically.

@spec prepare_arm(
  :gen_tcp.socket(),
  keyword()
) :: :ok

Brings the arm to a known-good, motion-ready state.

Sends the standard recovery sequence fire-and-forget: clean error, clean warning, enable motors, position-control mode, ready state. Options:

• :self_collision_check — when false, additionally disables the firmware's geometric self-collision model. Useful when probing joint limits (the collision model otherwise fires first on folded poses). Re-enable it afterwards by calling prepare_arm(socket, self_collision_check: true) or leaving the option out on a fresh simulator. Defaults to leaving the current setting untouched.

@spec reachable?(
  :gen_tcp.socket(),
  {number(), number(), number(), number(), number(), number()},
  keyword()
) :: {:ok, boolean()} | {:error, term()}

Probes whether a Cartesian pose is reachable, using the firmware's own kinematics.

Runs the pose through the firmware's IK, feeds the resulting joint configuration back through its FK, and measures the positional error: a reachable pose round-trips within a few millimetres, while an unreachable pose comes back wildly off (the firmware returns unclamped IK solutions). This is the reliable reachability probe — IS_TCP_LIMIT only checks the configured safety boundary.

pose is {x_mm, y_mm, z_mm, roll_rad, pitch_rad, yaw_rad}. Options:

• :tolerance_mm — maximum round-trip error to count as reachable (default 25.0; observed errors are < 5 mm for reachable poses and

  100 mm for unreachable ones)

Returns {:ok, boolean} or {:error, reason} on a protocol failure.

Sweeping this over a grid maps the arm's true reachable workspace.

@spec read_report(:gen_tcp.socket(), binary(), timeout()) ::
  {:ok, report(), binary()} | {:error, term()}

Reads one complete report frame from a report-stream socket.

buffer must be the unconsumed remainder (rest) from the previous call — starting fresh mid-stream would misalign frame boundaries. Returns {:ok, report, rest} or {:error, reason} (including {:error, {:bad_frame_length, n}} on a desynchronized stream).

@spec send_frame(:gen_tcp.socket(), binary()) :: :ok | {:error, term()}

Sends a frame without waiting for a response, then drains.

Some registers (notably MOTION_EN) may never get a reply from the simulator firmware; send those fire-and-forget.

@spec wait_until_ready(opts()) :: :ok | {:error, :timeout}

Blocks until available?/1 returns true, polling once per second.

Accepts the standard connection opts plus :timeout in milliseconds (default 60000). Returns :ok, or {:error, :timeout} if the firmware never became ready.

A freshly started simulator needs several seconds after its ports open before this succeeds; a physical arm is typically ready immediately.