Tool registry¶
Every end-effector tool used by code should have one versioned datasheet under
config/tools/. Simulation geometry, URDF links, calibration, and dataset
metadata must derive from that record instead of repeating dimensions.
Datasheet contract¶
Identify the schema version and coordinate origin.
State units, mounting frame, tip geometry, and contact assumptions.
Validate the fitted tool before generating derived geometry.
Record the datasheet revision with every run or placement artifact.
A datasheet’s calibration: block declares how the station probe may touch
the tool: face_kind: halo, a tube’s end, with the ring’s outside
(wall_radius_m), its hole (face_radius_m), where a rim touch puts the ball
(rim_touch_radius_m) and how far up the wall a side touch meets it
(side_touch_height_m). The needle cartridges and the laser’s nose declare
one. The probe calibration refuses a tool whose datasheet declares none
(ros/README.md §7). contact_reference: tube_end makes the planner ride the
tube’s end on the surface. accuracy_profile: needle-tube tells the probe
calibration that an edge pass will not trip the probe, because a cartridge’s
floating needles graze the ball. feature belongs to the retired one-arm
mechanical recipe, and nothing reads it; it stays because a datasheet’s bytes
are its tool identity, which the URDF and every recorded dataset carry. The
touch probe on the installed palette replaces that recipe’s pits
(docs/palette.md).
A fitted mechanical point is stored apart from tcp_z_m: a standoff tool
keeps its nominal working point, and a contact tool’s seated point carries an
unresolved writing-contact correction.
config/workspace.yaml retains mechanical_contact_* as calibration records:
coordinates, contact reference, accuracy profile, fit status and source session.
Motion consumers use pen_tip_offset_* and the resolved working TCP; the
historical contact record alone grants no motion or fit qualification.
On an arm’s ROS owner the fitted cartridge and its tip are runtime state, not
git: tatbot ros cartridge fit <tool> --arm <arm> records the cartridge in the
mount and tatbot ros calib apply its adopted tip, each in
~/tatbot-ros/calib/cartridge-<arm>.json (scripts/lib/cartridge_fit.py).
tool_spec.read_workspace lays that record over the section’s tool_id and tip
keys there, so a swap or an adoption needs no commit or deploy. The record keeps
a tip per cartridge type: fitting a type again starts from its last measured
tip, marked carried until a run measures this cartridge’s, and a type never
measured on the arm starts at its datasheet’s nominal tip. The section in git is
the seed the arm’s first fit or adoption copies.
Resolved geometry¶
The datasheet body profile, a planted touch-off, and the working TCP are
different facts. scripts/lib/tool_spec.py resolves them once for the real
URDF, simulation URDF, FK, and dataset metadata:
mount_from_bodyplaces the unchanged physical body profile.body_tip_offset_mis where rendered/contact material ends.tip_offset_mis what the calibration physically planted.tcp_offset_mis the working point used by FK and planning.
For contact tools those three endpoints must agree within 0.5 mm. A
well-conditioned fixed-point/pivot touch-off qualifies the contact vector. For
an axisymmetric profile whose mount origin lies on its centreline, the vector
also determines the contact-relevant axis; roll is unobservable but does not
change the geometry. Metadata therefore separates
contact_geometry_status: pivot-calibrated from
body_pose_status: axis-inferred instead of calling the
whole result provisional. Non-contact tools may separate material and TCP only by their explicit
datasheet standoff.
Dataset metadata always records the concrete geometry that ran, including a nominal fallback and its source; null offsets are not a geometry contract.
The drawn line¶
contact_radius_m is collision and TCP geometry and tip_detail is render
geometry; neither says how wide a line the tool lays. That is the optional
line: mapping, recorded like measured: and validated at load:
line:
width_mm: 0.3 # in (0.05, 2.0]
status: assumed # measured | assumed
utc: 2026-09-15
method: "needle grouping's width; swatch not yet measured"
substrate: silicon_skin
It is a deposition measurement on one substrate at one working speed, exposed
as ToolSpec.line_width_m; a partial block refuses. The DBV3 recipe records its
acquisition pen width. ROS preparation binds the fitted tool’s physical footprint
without editing the acquired geometry. The fill planner’s source/fixture tooling
can use the footprint for deduplication; native DBV3 paths retain repeated passes.
A status: assumed value is a placeholder for a measurement: draw a short swatch
at the working speed on the substrate, measure the line against a known pitch
(or a loupe), then record measured with the UTC and method.
The pen’s passes over each spot (tatbot_ink.passes: a program’s
stats.passes, a run’s passes.json) are counted at line.width_mm, else at
each path’s generation width; tatbot ros compile --mark-width-mm counts at
another width, and stats.passes.marks says which. No needle cartridge’s mark
on skin is measured, so the 3RL counts at its 0.3 mm paths.
The fade: fade_lift_mm¶
A stroke may fade: its deposition per point (a whip from tatbot art shade) rides
(1 - deposition) * fade_lift_mm higher than the pen’s path, so deposition 0 lifts
the mark out (ros/README.md 4.2). fade_lift_mm, in (0, 4] mm like the pen trim’s
reach, is the lift over which the tool’s mark goes from full to nothing: read it from
a ride ladder on the tool’s substrate. The 3RL records 0.7 mm: a fade ladder on the
silicone skin, five lines rising evenly from a -1.75 mm trim, inked 4-6 mm of each
(2026-11-03). It is measured from that depth, so a deeper ride fades later. The other
cartridges record none yet. A tool without it draws no fading stroke: the
compiler refuses one. On paper a fade is a line breaking
up; whether a lifted needle’s gradient survives healing on skin is untested.
The stroke: press or ride¶
A rotary machine’s tip reciprocates through its stroke. A page touch trips
only once the tip is pushed up to the top of that stroke, where it stops, so
the touched page is where the tip meets the surface at the top of its stroke,
whether the machine runs or not. Two optional fields place the stroke, and
ToolSpec.stroke_m and ToolSpec.tip_out_at_top_m validate them at load:
stroke_mm: 4.0 # the machine's stroke with this cartridge, in (0, 6]
tip_out_at_top_mm: -1.0 # the tip out of the cartridge's tube at the top of the stroke; negative: inside it
The collar that sets the tip’s protrusion moves the TCP, so a change needs a
new touch-off. How the drawing path uses these is motion tuning, motion.yaml
pen.mode, read at every draw against the fitted tool’s datasheet:
press: the machine stays off, the tip stays at the top of its stroke, and the path presses
pen.press.lift_minto the page; the arm’s and mount’s give keeps the tip on the surface.ride: the drawing stack runs the machine through its switch and the path rides
pen.ride.fractionofstroke_mmover the touched page, so the running tip meets the surface that far down each stroke and would reach the rest past it.
A tool that records neither field, or whose tip sits inside its tube at the
top of the stroke (a touch would meet the tube), cannot ride, unless the
tube’s end is its contact reference (calibration.contact_reference: tube_end, a needle cartridge). Its touches and wrist gauge then measure the
tube’s end, which is the TCP, so the path is that end’s height and riding
needs only stroke_mm. needle_reach_mm records how far the needles pass the
tube’s end at the bottom of the stroke; the run’s pen down event then says
how deep they go.
Public examples should use a clearly marked fixture tool. Physical dimensions, calibration values, and deployment choices that are not needed to build the software remain private.
Contact qualification is evidence-bound by the touch-off’s tool/frame identity, pose count, condition number, rotation spread, residual, datasheet tip range, and seat-angle range. Held-out and leave-one-out disagreement travel as uncertainty metadata; they never widen the collision/marking band. Optional explicit body geometry separately revalidates its report digest and current-seat identity, falling back to the inferred axis if that evidence is missing or stale. Physical capture procedures and calibration values stay in the private operator documentation rather than this public contract.
Cartridge exchanges¶
Every fitted needle cartridge dips (ink.mode: real, ros/README.md §6).
ink.mode: cartridge stays in the vocabulary for a self-inking refill, which
writes from its own supply and never dips; no shipped datasheet declares one.
Bind each acquired DBV3 pen to a resource with tatbot-inks/3. A resource may
set its own dip: values (mm_per_dip, dwell_s, above_ink_m, drain_s,
drain_above_rim_m) over the datasheet’s. drain_s is a hold over the cap
after the dwell with the machine running, drain_above_rim_m over its rim; no
datasheet states one yet, so no dip drains until a lab drain ladder measures
it, and a drain without a stated height holds 3 mm over the rim.
A cartridge fitted on another’s dip values says so: dip.card: {status: borrowed, from: [...]}. tatbot ros compile refuses it for a design until
its dip card is read (lab) and the datasheet says status: read
with the study; --allow-borrowed-dip draws on the borrowed values anyway,
and the program’s resource then carries dip_card: borrowed. The 1007RL
(lutin-7rl) is the first: its depth and dwell are the 11RL’s and its
mm_per_dip the 3RL’s first figure. At a resource change the arm lands and the operator swaps the
cartridge by hand. Cartridges of
one machine share its body, so the resumed run keeps its measured page; a
different physical geometry needs calibration and new page touches. A fresh
cartridge of the same type can still seat its tube’s end millimetres from the
last one’s: a new 3RL on the xArm (2026-11-09) put its ink 2-3 mm off the plan.
Calibrate the tip again after one (tatbot ros calib sweep, apply), then the
station touch and its height, then each wrist camera’s calib wristcam and
calib gauge, which hold the tip in the camera’s frame.