Administering a probe

This is how to run meshint-probe after it is installed. The build is in probe-installation.md. The controller side of enrollment is in controller-administration.md.

The probe opens the connection. The controller does not connect to it. The only controller it will talk to is the one named by --url whose certificate matches --pin. A redirect is refused. I/Q is not sent.

Start

meshint-probe --url https://192.0.2.10:8443 --pin controller-cert.pem \
  --latitude 51.5 --longitude -0.12 --altitude 120 --heading 90 --clock gpsdo

--url is the controller probe port, not the admin port. --pin is the controller certificate for this shipment. --clock is gpsdo or free.

Each contact prints one word and no report body:

Word	Meaning
`pending`	The controller has not approved this host. No dwell is analysed.
`approved`	Approved, and the reply did not include a configuration with a `probe_id`. A scan plan has not been stored yet.
`configured`	This contact has just stored a configuration with a `probe_id`. It did not analyse on this contact. The next contact walks the stops.
`scanning`	This contact walked the stops and offered the reports from that walk.
`link_down`	The handshake or the POST failed. New reports were queued.

scanning means the probe walked the configured frequencies and analysed a dwell at each. It does not mean a radio was tuned. MeshInt has no scanner.

--once makes a single contact and exits. Without it the probe repeats about once a second. --state (default probe-state.json) keeps the configuration, the software version, and any queued reports. The next start continues from that file.

Identity

host_id is a hash of the platform machine id. The raw id is not sent. On macOS the source is the platform UUID. On Linux it is /etc/machine-id.

meshint-probe --show-host-id

That prints the id and does not connect. --host-id replaces the hash. Use it when several probes share one computer. Each probe still needs its own --state file, or they will overwrite one another.

--airframe is the aircraft name sent on every hello. Probes that send the same name are grouped as one airframe. The controller stores the aircraft type and the description. The probe does not.

Position

--latitude, --longitude, and --altitude are the fix for this run, in degrees and metres. --heading is degrees from north. --speed is ground speed in metres per second.

--nav is a JSON file with those same names: latitude_deg, longitude_deg, altitude_m, and optionally heading_deg, speed_m_s, and clock. When that file can be read, it is the fix and the matching flags are not used. A position is sent only when latitude, longitude, and altitude are all present.

The probe reads a fix the aircraft supplies. It does not read a GPS receiver. Give the fix as flags, or as the navigation file below. The computer, the radio, the position source, and the link are described in hardware.md.

I/Q input

The probe builds each dwell itself. It does not read a live radio. A radio fitted to this computer is described in hardware.md. A live dwell would have to come from software outside MeshInt.

--recording is a little-endian interleaved cf32 file. --sample-rate and --center-freq are required with it. --format accepts only cf32.

After the probe is approved and holds a configuration, each stop in the scan plan is one dwell:

If the stop's centre frequency and sample rate match --center-freq and --sample-rate, the dwell is the beginning of the file, long enough for the configured dwell and no longer than the file.
Otherwise the dwell is silence, and the analyser reports nothing for that stop.

With no recording, every stop is silence. A status report is still sent after the walk.

Do not point --recording at a customer capture you are not prepared to keep on that machine. The samples stay there. They are not uploaded.

Enrollment, from the probe

Start the probe with --url and --pin. The first contacts print pending.
On the controller, accept that host. The probe is not edited during acceptance.
The following contact receives the configuration, including probe_id. Later contacts walk the stops and send detection and status reports.

Until acceptance, reports are not analysed and anything offered is discarded by the controller. Approval is remembered for that host_id. A restarted probe with the same state file and the same host id does not need to be accepted again.

If the link fails after a configuration is held, the probe keeps the configuration, keeps analysing, and queues reports. The queue holds 2000 messages. Past that, a status report is dropped before a detection.

Software update

The controller may offer one file. The probe downloads it with GET /update on the same URL, checks the sha256, and stores it under --update-dir (default probe-updates/). It does not follow a redirect to fetch the file, and it does not execute the file. The next hello reports the staged version, with no reports on that hello. The probe keeps running the binary it was started with.

What this administration does not include

The scan plan, the antenna description, and SAPIENT. Those are controller settings.
Flight control. A travel cue in the state file is advice the platform may ignore.
Any connection except the controller named by --url.