Introduction

Scope

The scope of this manual is instrument-team developers and integrators who author OTTO Instrument Packages (IPs) for ELT-era instruments using the IpTool YAML authoring layer, its compiler (ifwIpToolCompiler) and validator (ifwIpToolValidator).

The manual does not describe the OTTO IP JSON schemata themselves nor the CII Config Service in depth; for those, the appropriate ESO documentation must be consulted (see the references in Overview).

What IpTool is

IpTool is the YAML authoring layer for OTTO Instrument Packages (IPs). An Instrument Package is the configuration bundle an instrument’s software team delivers to ESO’s observation preparation team so observations with that instrument can be prepared: it declares the observation templates the instrument supports, what parameters they take, what observing constraints apply, and what checks the astronomer must complete before an observation is accepted. Without an IP, an instrument is invisible to ESO’s preparation tools and no observation can be prepared for it.

The OTTO IP format itself is JSON. JSON is fine for machines but a poor authoring format: no comments, no inheritance, and a lot of repetition between similar templates. IpTool lets you author the same content in YAML — with comments, with file includes, and with per-template overrides on shared parameter definitions — and compiles it down to the OTTO JSON the preparation tools expect.

IpTool is shared ESO infrastructure for ELT-era instruments, not a tool built for any single instrument. The first real-instrument workload is FORS3, but the same authoring conventions, validator, parallel compile, and tooling are intended to serve every ELT instrument that joins (MICADO, METIS, HARMONI, MOONS, ANDES, and others). Feedback from one instrument team becomes a feature for every subsequent one.

What IpTool gives you

• A YAML authoring layer, based on the CII Config Service, with file inclusion (!cfg.include) and field-level inheritance (!cfg.merge) over typed instances.

• A compiler (``ifwIpToolCompiler``) that produces every artefact defined by the OTTO IP schemata — Format, TemplateIndex, Template Signatures, Constraints, Checklist, Laser, plus sample OBDs and Sequencer Script stubs ready to dry-run in the ELT IFW Sequencer. Parallel template loading by default keeps the inner loop fast even on real-instrument-sized projects.

• A validator (``ifwIpToolValidator``) that checks a generated IP against the OTTO JSON schemas.

• Three bundled examples: TSTINS (“test instrument”) exercising every shape the OTTO IP schemata define, TSTNLS (“test instrument, no laser”) covering the no-laser branch, and the full-scale FORS3 IPT (77 templates, 5-prefix parameter library) showing what a real-instrument IP looks like end-to-end. See Examples.

Who should read this manual

Instrument-team developers and integrators who need to author an IP for a new or evolving ELT-era instrument. The manual assumes you have heard of OTTO IPs but does not assume you have built one before. Read the chapters in order:

• Overview — what an IP actually is, what artefacts make it up, and how IpTool fits into the operations pipeline. Also introduces the CII Config Service features IpTool relies on.

• Schema — the three IpTool YAML file roles and the typed instances inside them, with an end-to-end walkthrough of one parameter from author’s YAML to OTTO JSON.

• CLI — the compiler and validator, with a step-by-step Quickstart you can run in five minutes.

• Examples — the bundled TSTINS example walked through template by template, plus the full-scale FORS3 IPT example as an at-scale reference (77 templates, per-prefix parameter library).

• Tutorial — recipes for the tasks an instrument team actually performs (bootstrap a new instrument; author each parameter type; per-template overrides; common validator errors).

Acronyms

Acronym	Expansion
CII	Common Infrastructure for Instrumentation.
ELT IFW	Extremely Large Telescope Instrument SoftWare framework.
IP	Instrument Package.
IPT YAML	IpTool YAML source file (.ipt.yaml).
OB	Observation Block.
OBD	Observation Block Description.
OTTO	“Otto Tackles Telescope Observations”.

Glossary

Term	Meaning
CFGPATH	Colon-separated list of root directories the CII Config Service searches for files referenced by relative path (!cfg.include, schema lookups). Set by the ESO environment, typically includes $INTROOT/resource and the system resource trees.
CII Config Service	The CII service IpTool builds on: a typed YAML configuration engine providing !cfg.include, !cfg.merge, !cfg.typedef and type-checked instances. See the CII Config Service manual.
ELT IFW Sequencer	The ELT IFW component that executes Observation Block Descriptions (OBDs) by running the instrument’s Sequencer Scripts.
Instrument Package (IP)	The full set of OTTO JSON artefacts an instrument team produces and ESO’s observation preparation tools consume. Defines the observation templates the instrument supports, their parameters, the observing constraints that apply, and the checklist items astronomers must complete. See Overview.
INTROOT / PREFIX	The user-local install root used by ESO build systems (waf install). $INTROOT is the per-user development install root; $PREFIX is the install destination the running waf command writes into (usually the same as $INTROOT).
IpTool	The tool described in this manual (ifw-iptool).
Keyword	In OTTO context: a single parameter declaration (one IpToolParameter instance). The dotted FITS-style name (DET.WIN1.NX) is the parameter’s identifier; the keyword’s type (integer, keyword, ra, …) is one of the IpTool value types and constrains its allowed values.
Observing constraint	One of the OTTO-named observing conditions an OB depends on (seeing, airmass, moonDistance, pwv, fli, strehlRatio, twilight, skyTransparency, turbulence). Authored in the IP-wide metadata; enforced by scheduling.
Parameter	Used interchangeably with Keyword in this manual: one IpToolParameter instance declaring a single value an observation template carries.
Phase 1 / Phase 2	ESO’s proposal preparation (Phase 1) and observation preparation (Phase 2) workflow steps. Phase 1 templates are the ones an astronomer can pick when writing a proposal; Phase 2 templates cover the rest (acquisition, calibration, technical).
PYTHONPATH	Colon-separated list of root directories the Python runtime searches for importable packages and modules. The ELT IFW Sequencer expects the IpTool-generated stubs to be reachable via PYTHONPATH.
Sequencer Script	The instrument-team-authored Python module that implements one observation template’s logic. The Sequencer loads it via app/library.cfg. IpTool generates stubs (skeletons) at compile time; the instrument team replaces them with the production scripts.
Template	An observation template: a named, parameterised “kind of observation” the instrument supports (e.g. tstins_img_obs_crsplit). Authored as one IpToolTemplate instance in a *.tpl.ipt.yaml file; emitted as one Template Signature JSON file.
Template Signature	The OTTO JSON file describing one template (templates/<templateName>.json). Two OTTO schemas apply: Fmt1TemplateSignature.json for acquisition templates, TemplateSignature.json for the others.