feat(examples): seed_marine.py + sensor field guides for the Aeolian Fortune demo

field-guides/README.md

@@ -0,0 +1,11 @@
+# Condition Monitoring — Field Guides
+
+Practical guides for technicians taking readings on the Mechbase marine demo routes.
+
+| Guide | Sensor / Instrument | Measurement |
+|---|---|---|
+| [Vibration](vibration.md) | TE Connectivity WVS wireless tri-axial accelerometer | Velocity (mm/s RMS) |
+| [Thermography](thermography.md) | FLIR Edge series handheld thermal camera | Surface temperature (°C) |
+| [Ultrasound](ultrasound.md) | Handheld ultrasonic detector | Signal level (dB) |
+
+Each guide covers the instrument, how to set it up and take a reading correctly, and how to enter the result in Mechbase.

field-guides/thermography.md

@@ -0,0 +1,79 @@
+# Thermography — Field Guide
+
+Camera: **FLIR Edge series** handheld (visual + thermal, MSX enhancement, FLIR ONE app)
+
+---
+
+## How the camera measures temperature
+
+Thermal measurements show the **surface** temperature of the target. Accuracy depends on three factors:
+
+| Factor | What to watch |
+|---|---|
+| **Distance to target** | Closer = better spatial resolution and spot size. Get as close/zoomed as safely possible. |
+| **Ambient temperature** | Note ambient; it is the reference for ΔT calculations. |
+| **Emissivity** | How efficiently the surface radiates heat (see below). |
+
+### Emissivity
+
+- **Matte / painted / oxidised surfaces** — good emitters; the camera's default ~0.95 setting is a fair approximation.
+- **Bare / glossy / shiny metal** — poor emitters; the default setting will under-read. Apply a strip of high-emissivity tape or a dab of matt paint over the spot, **or** manually set the known emissivity in the camera before reading.
+
+---
+
+## Camera setup
+
+1. Power on; let the camera warm up briefly.
+2. Set the **temperature range** to suit the expected target (e.g. a wider range for electrical gear under fault conditions).
+3. Choose a suitable **colour palette** (e.g. Iron or Rainbow for electrical; Greyscale for quick scans).
+4. Enable **MSX** and set the MSX distance to match the target distance — this overlays visual detail on the thermal image for easier interpretation.
+5. Use the **adjustable measurement spots** to track the hottest and coldest points in the frame. The camera periodically auto-calibrates (mechanical shutter click + brief freeze) — this is normal; wait for it to complete before reading.
+
+---
+
+## Inspection technique
+
+### General
+
+- Inspect under **normal / representative operating load** — an unloaded circuit or idle machine hides faults.
+- Keep the **view angle within ~30° of perpendicular** to the target surface to limit reflection error.
+
+### Electrical (switchboards, distribution panels)
+
+1. Open the inspection cover or use an IR window where required (PPE: arc-flash rated).
+2. Scan **busbars, breakers, incoming terminals, and all connections**.
+3. Compare the **same component across all three phases** — a phase running hotter than its siblings under similar load indicates a loose or corroded connection, an overloaded circuit, or a failing device.
+4. Note the hottest spot temperature (°C) and the ΔT above ambient or the reference phase.
+
+### Mechanical (motors, bearings, pumps)
+
+1. Scan **bearing housings** and **couplings**.
+2. Compare each bearing housing against its pair or against its known baseline.
+3. A bearing running hotter than its baseline or its paired housing suggests a lubrication or wear issue.
+
+---
+
+## Judging severity
+
+Judge findings by **ΔT** (temperature rise over a reference point — ambient air, the established baseline, or a similar phase / component), not by absolute temperature alone.
+
+| ΔT (over reference) | Typical severity |
+|---|---|
+| < 10 °C | Monitor — recheck at next route interval |
+| 10–30 °C | Investigate — plan corrective action |
+| > 30 °C | Act promptly — potential imminent failure |
+
+*These are general guidelines; the Mechbase route item shows the configured limit band for this specific point.*
+
+---
+
+## Safety
+
+- Do **not** point the camera at the sun or laser sources.
+- For live electrical panels, maintain safe working distance and use appropriate PPE; use an IR window or a non-contact safe zone wherever possible.
+
+---
+
+## Recording the reading in Mechbase
+
+Open the assigned **Route** → tap the **Measurement Item** for this thermal point → the item shows the limit band (minor alert: ~65 °C; major alert: ~90 °C in this demo). Enter the **maximum spot temperature** (°C) observed at the target and confirm.

field-guides/ultrasound.md

@@ -0,0 +1,73 @@
+# Ultrasound — Field Guide
+
+Instrument: **Handheld ultrasonic detector** (contact/stinger probe + airborne horn; outputs a dB reading for manual entry)
+
+---
+
+## Three main applications
+
+| Application | Probe | What you are detecting |
+|---|---|---|
+| **Bearing condition** | Contact / stinger probe on bearing housing | Structure-borne ultrasound from rolling-element wear or inadequate lubrication |
+| **Leak detection** | Airborne horn | Compressed-air, steam-trap, and valve leaks |
+| **Electrical** | Airborne horn | Partial discharge, arcing, and corona in switchgear |
+
+---
+
+## Bearing condition checks
+
+1. Fit the **contact (stinger) probe** firmly to the bearing housing at the designated spot — same location and orientation every visit.
+2. Adjust the instrument's frequency / sensitivity to the manufacturer's recommended setting for rotating-equipment surveys.
+3. Listen through the headset and read the **dB level** displayed.
+4. Record the value; compare to this point's baseline (see Interpretation below).
+
+**Tip:** ultrasound detects incipient bearing faults earlier than vibration or thermography, especially on slow-speed bearings. It is also the primary tool for identifying lack of lubrication before a bearing overheats.
+
+---
+
+## Leak surveys (compressed air / steam)
+
+1. Fit the **airborne horn** (focusing cone).
+2. Sweep the area methodically from a safe distance.
+3. Home in on the direction of the **loudest dB reading** — leaks produce a strong high-frequency hiss.
+4. Once located, move closer to confirm and note the location, dB level, and estimated leak size.
+
+**On a vessel:** cover compressor discharge lines, air receivers, valve glands, steam traps, and flexible hose connections.
+
+---
+
+## Electrical surveys (switchgear / panels)
+
+1. Fit the **airborne horn**.
+2. Hold the instrument near (not inside) the panel or cable tray.
+3. Partial discharge, arcing, and corona all produce characteristic ultrasonic signatures.
+4. Note the dB level and location of any hot spot.
+
+---
+
+## Interpreting bearing readings — trend-based thresholds
+
+Always compare against the **same point's historical baseline**, not an absolute number.
+
+| Rise over baseline | Indication |
+|---|---|
+| < +8 dB | Normal variation — continue monitoring |
+| ~+8 dB (sustained) | Early / incipient wear or lubrication deficiency — investigate, consider re-lubrication |
+| +12–16 dB | Advanced wear — plan maintenance |
+| > +16 dB | Imminent failure — act promptly |
+
+A single elevated reading can be caused by load spikes or probe placement variation. Confirm with a second reading before escalating.
+
+---
+
+## Good technique habits
+
+- Use the **same probe, same spot, same pressure** every visit — variability in contact pressure changes the dB reading.
+- Take readings when the machine is running under **normal operating load**.
+- Note any unusual audible signatures (e.g. grinding, intermittent clicks) that the dB number alone does not capture.
+
+---
+
+## Recording the reading in Mechbase
+
+Open the assigned **Route** → tap the **Measurement Item** for this ultrasound point → the item shows the limit band (minor alert: ~40 dB; major alert: ~50 dB in this demo). Enter the **dB value** displayed on the instrument and confirm.

field-guides/vibration.md

@@ -0,0 +1,81 @@
+# Vibration Monitoring — Field Guide
+
+Sensor: **TE Connectivity WVS** wireless tri-axial accelerometer
+
+![TE Connectivity WVS vibration sensor](images/te-wvs-sensor.jpg)
+
+*Note the X/Y/Z axis marker on the hex base (align **X** with the shaft), the
+magnetic twist-mount indicator, the threaded/stud base, and the Ex ia IIC (ATEX/IS)
+rating for hazardous machinery spaces.*
+
+---
+
+## Mounting method — decision tree (best → temporary)
+
+| Method | Use case | Notes |
+|---|---|---|
+| **Stud mount** | Permanent monitoring points | Best frequency response; solid metal-to-metal contact; conveys the full spectrum |
+| **Epoxy mount** | Permanent; no stud possible | 2-part hard-curing epoxy (e.g. Loctite AA 330). Detach magnetic base, epoxy it to machine, re-thread sensor. |
+| **Two-pole magnet** | Curved housings (e.g. motor end caps) | Two feet grip curved surfaces. Gently roll sensor into contact — do not thump it down. Do **not** use a flat magnet directly on a curved surface. |
+| **Flat magnet on glued/soldered metal target** | Painted or curved surfaces where direct contact is impractical | Epoxy or solder a small flat metal target to the machine; mount flat magnet on the target. |
+| **Flat magnet on clean flat surface** | Temporary spot-checks only | Magnets shift on dirty or irregular surfaces. For trend data, prefer a permanent mount. |
+
+---
+
+## Surface preparation
+
+- Remove **all paint and rust** from the mounting area — multiple paint layers and rust severely dampen or block the signal.
+- Vibration must travel through solid, continuous metal; any gap or joint in the path corrupts the reading.
+- Target a **robust, flat, fully cleaned bearing-housing area**.
+
+---
+
+## Where to mount — placement
+
+- Mount as close as feasible to the **monitored bearing**.
+- Target the **load zone**: the section of the bearing housing that carries the rotating shaft — defects show up earliest there.
+
+**On marine machinery take points at:**
+
+1. Motor non-drive end (NDE) bearing housing
+2. Motor drive end (DE) bearing housing
+3. Driven-end bearing (pump / compressor / fan / purifier)
+
+---
+
+## What to avoid
+
+Do **not** mount on:
+
+- Thin cooling fins
+- Plastic covers or fan shrouds
+- Component enclosures
+
+These surfaces resonate at their own frequencies or attenuate the true signal, producing inaccurate data.
+
+---
+
+## Sensor orientation (axis alignment)
+
+The WVS is tri-axial (X / Y / Z axes).
+
+1. Align the **X axis** (marked on the sensor body) with the motor **drive shaft**.
+2. Keep the **same orientation on every visit** and across comparable machines.
+3. Take readings at the **same physical point** each visit.
+
+Inconsistent orientation makes trend analysis unreliable — today's X reading becomes last month's Y.
+
+---
+
+## Taking the reading
+
+1. Mount the sensor at the designated point using the appropriate method above.
+2. Allow a brief settle time after mounting (especially magnetic mounts).
+3. Confirm the sensor is paired and transmitting in the WVS app / Mechbase.
+4. Note the velocity value (mm/s RMS) displayed.
+
+---
+
+## Recording the reading in Mechbase
+
+Open the assigned **Route** on your device → tap the **Measurement Item** for this point → the item shows the limit band (minor / major alert thresholds). Enter the velocity value (mm/s) and confirm. The system records the timestamp, value, and your user ID automatically.