Administering the controller

This is how to approve probes, configure them, read the picture they produce, and emit SAPIENT. Installing and starting the process is in controller-installation.md. Using the dashboard is in controller-dashboard.md.

The admin page is GET / on the admin port, for example http://127.0.0.1:9444/. It is localhost only and has no separate credential. Log out hides the console in the browser until Open admin is chosen. It does not add a login. The same actions are available to anything that can connect to that localhost port.

The header shows the controller version, three icons that hide or show the probe list, the detection list, and the probe pane, View, Configuration, Light display, and the session label admin with Log out. Light display is stored in the browser.

Enrollment

1. Start the controller and leave the admin page open.
2. Start each probe with that controller's probe URL and pin. See probe-administration.md.
3. A new host appears under the airframe name it sent, or under "No airframe", with an Accept button. A hello in the last 15 seconds shows an outline LIVE mark. Reports from that host are discarded, so the mark does not turn solid.
4. Press Accept. The controller assigns probe-1, probe-2, and so on.

From the command line, on the same machine:

meshint controller probes --admin http://127.0.0.1:9444
meshint controller approve --admin http://127.0.0.1:9444 --host-id <host_id>

--probe-id on approve sets the id instead of the next probe-N. The airframe name is not edited here. It stays the name the probe reported.

Approval is remembered in state.json. The same host_id on a later connection is already approved.

Probes

The list is grouped by airframe name. Hide on a heading removes that airframe from the map and from the fitted view. The rows stay, dimmed, and Show puts them back. The Show button stays at full strength. Choosing a hidden probe does not move the map.

LIVE means the controller has received a hello in the last 15 seconds.

No mark means the probe has not been heard for 15 seconds.

Choosing a probe centres the map on its last position. The zoom stays as it is, unless the view is wider than 25°, in which case the map zooms in.

The probe pane then shows last contact and last detection, each as a UTC time and an age. Under that it shows the host, airframe, type, description, version, configuration status, clock, and antenna. Last contact is when the controller received the latest hello. Last detection is the time of the latest detection that probe reported.

The antenna controls stay disabled until an approved probe is selected. A pending probe can be selected. Its antenna can be sent once it is accepted.

Configuration sent to probes

Configuration applies to approved probes on their next session. The probe does not pull it on its own schedule beyond its usual contact.

Scan plan. In Configuration, the Scan plan tab. start_hz, stop_hz, step_hz, sample_rate_hz, and dwell_s. This is the list of stops the probe walks. It does not tune a radio. The same plan goes to every approved probe.

meshint controller configure --admin http://127.0.0.1:9444 \
  --start-hz 3200000000 --stop-hz 3400000000 --step-hz 20000000 \
  --sample-rate 20000000 --dwell 5

--baseline probe-1:0.5:90 sets a baseline length in metres and an azimuth in degrees for one probe. The current probe session still reports one channel and localisation.status of insufficient.

Antenna. In the probe pane, for the selected approved probe. Omnidirectional, or directional with a beam width and a direction relative to the airframe. Send configuration. The row shows configuration pending until a later hello reports the new revision, and then the row tooltip shows configuration sent.

Airframes. In Configuration, the Airframes tab. A description and a type for a name the probes already report: balloon, small fixed-wing, large fixed-wing, or multi-rotor. That type is the icon. It is not sent back to the probe as a new name.

Software update. In Configuration, the Software update tab. One version and one file. The file is stored under the state directory and offered to every approved probe whose hello does not already report that version. The probe stores it and does not run it. The row shows update pending until a later hello reports that version, and then the tooltip shows update confirmed.

A change of scan plan, antenna, or baseline bumps the revision. The first reply that carries the new revision does not clear the pending state. The probe reports the revision only after it has stored the configuration.

The picture

Detections from different probes join one subject when their centre frequencies are close and their times are within 50 ms. The area is insufficient, bearing, hyperbola, or fix. The detection list shows the area, the centre frequency, the arrival sector, and the probes that contributed. Historic subjects are dimmed. Choosing a probe filters this list to the subjects that probe contributed to. Show all clears the filter.

meshint controller detections --admin http://127.0.0.1:9444

The map draws the probes that have a position and are not hidden, their beams, and the area. Drag pans and the wheel zooms. Show all fits the visible probes. View loads KML in the browser only, and sets line thickness and label size relative to the zoom. Sample layers are in examples/kml.

Simulate mesh, at the foot of the probe list, flies four airframes over London, at least 10 km apart, without using the analyser. It starts off, including after a restart. Turning it off stops new simulated reports and leaves the probes already stored.

SAPIENT

Emission stays off until you enable it. In Configuration, the SAPIENT tab, set an endpoint and turn on Emit detection updates.

The controller sends a registration, then a detection report per subject. The report does not name the radio. A fix on TCP is longitude and latitude in degrees so a plotting node can draw it. The JSON log stays in the --sapient file either way, including while emission is off. The audit record stores the scheme and host of the endpoint, not a credential from the URL.

Probes are not SAPIENT nodes. Nothing in the probe configuration turns emission on.

Records

state.json in the state directory holds approvals, the scan plan, subjects, detection history, airframe descriptions, cues, SAPIENT settings, and the staged update. audit.jsonl keeps the latest 1000 actions: approvals, airframe changes, scan-plan changes, probe reconfiguration, SAPIENT on or off, simulation on or off, a staged update, and a confirmed software version. It does not keep update bytes or positions.

Keep the state directory, and the private key inside it, on the controller machine.