PigStick API Reference

Returns device identity, firmware version, and hardware capabilities.

Response

{
  "device": {
    "serial": "PS2609A0110",
    "name": "pigstick-0110",
    "firmware": "2.2.72",
    "uptime": 3621,
    "bootCount": 47,
    "capabilities": {
      "audio": true,
      "magnetic": true,
      "gps": true,
      "battery": true
    },
    "limits": {
      "maxWsClients": 2,
      "maxEvents": 103
    }
  }
}

Comprehensive device state snapshot including recorder, GPS, power, and connectivity.

Response

{
  "status": {
    "timestamp": 1773868800000,
    "device": "pigstick-0110",
    "serial": "PS2609A0110",
    "firmware": "2.2.72",
    "app": "2.2.95",
    "uptime": 3621,
    "storage": {
      "eventCount": 12,
      "total": 10379264,
      "used": 1245184,
      "free": 9134080,
      "evictionCount": 0
    },
    "job": {
      "client": "Acme Pipeline",
      "jobName": "Run-042",
      "operator": "J. Smith"
    },
    "recorder": {
      "state": "armed",
      "eventCount": 12,
      "freeSpace": 9134080,
      "captureProgress": null,
      "holdoffRemainingMs": null,
      "lastTriggerTime": 1773868500000,
      "capturesSinceBoot": 3,
      "autoArm": false,
      "audioEnabled": true
    },
    "gps": {
      "timeSynced": true,
      "fix": true,
      "fixQuality": 1,
      "satellites": 7,
      "lat": 30.267153,
      "lon": -97.743057,
      "altitude": 149.20,
      "speedKnots": 0.04,
      "speedMps": 0.0206,
      "utcEpochMs": 1773868800000
    },
    "power": {
      "voltage": 4.05,
      "percent": 82,
      "charging": false,
      "source": "usb"
    },
    "temperature": 42.5,
    "wifiConnected": false,
    "mqttConnected": false,
    "iotJobsBusy": false,
    "startupBehavior": {
      "armOnBoot": false
    }
  }
}

Battery voltage, charge percentage, and power source.

Response

{
  "power": {
    "voltage": 4.05,
    "percent": 82,
    "charging": false,
    "source": "usb"
  }
}

Cached accelerometer axes, activity, and device-owned orientation state. Reading this endpoint does not poll the sensor hardware.

Internal MCU temperature reading.

Response

{
  "temperatureC": 42.50,
  "temperatureF": 108.50
}

Error Response

{
  "error": "sensorReadFailed"
}

System clock status. Time is synced from GPS satellites.

Response (synced)

{
  "synced": true,
  "time": "2026-03-17T14:30:00"
}

Response (not synced)

{
  "synced": false
}

Current recorder state, capture statistics, and active job context.

Response

{
  "recorder": {
    "state": "armed",
    "eventCount": 12,
    "freeSpace": 9134080,
    "captureProgress": null,
    "holdoffRemainingMs": null,
    "lastTriggerTime": 1773868500000,
    "capturesSinceBoot": 3,
    "autoArm": false,
    "audioEnabled": true,
    "activeJob": {
      "client": "Acme Pipeline",
      "jobName": "Run-042",
      "clientDir": "Acme_Pipeline",
      "jobDir": "Run-042",
      "createdAt": 1773782400,
      "notes": ""
    }
  }
}

Current trigger, audio, and speed estimation configuration.

Response

{
  "config": {
    "trigger": {
      "mode": "zeroCrossing",
      "thresholdPercent": 50,
      "holdoffMs": 5000,
      "preDurationMs": 10000,
      "postDurationMs": 10000
    },
    "audio": {
      "enabled": true,
      "sampleRate": 8000
    },
    "speed": {
      "intervalWindow": 5,
      "segmentLengthFt": 40,
      "pigThreshold": 30
    },
    "autoArm": false,
    "activeJob": { ... }
  }
}

Update recorder configuration. All fields are optional—only provided fields are changed.

Request Body

{
  "triggerMode": "threshold",
  "threshold": 40,
  "holdoffMs": 3000,
  "audioEnabled": true,
  "autoArm": false
}

Response

{"status": "ok"}

Errors

• 400 — Invalid JSON or invalid triggerMode value
• 409 — Config rejected (capture in progress)

Arm or disarm the event recorder.

Request Body

{"armed": true}

Response

{
  "recorder": {
    "state": "armed",
    "armed": true
  }
}

Start a device-side manual passage capture using the PigStick's magnetic and audio pre-trigger ring buffers. The normal post-trigger capture, LittleFS storage, job export, and multi-viewer notification pipeline is used.

Response (202 Accepted)

{"accepted":true,"captureOrigin":"manual","audioPartial":false}

Returns the active field magnetic sensitivity level, profile name, dirty state, and preset availability.

Apply a field sensitivity preset. Rejected while the recorder or update service is busy.

Request Body

{"level":"medium"}

Returns value-blind MFL offset calibration state, running flag, and operator message.

Starts local MFL offset calibration. Rejected while the recorder or update service is busy.

List all event metadata for the active job.

Response

{
  "events": [
    {
      "id": 1,
      "timestamp": 1773868500000,
      "triggerSample": 2000,
      "magSamples": 4000,
      "magRate": 200,
      "audioSamples": 160000,
      "audioRate": 8000,
      "peakMagnetic": 1842,
      "triggerMode": 0,
      "threshold": 50,
      "latitude": 30.267153,
      "longitude": -97.743057,
      "hasAudio": true,
      "magDataSize": 8000,
      "audioDataSize": 40000
    }
  ],
  "total": 1,
  "freeSpace": 9134080
}

Single event metadata with additional fields.

Response

{
  "id": 1,
  "timestamp": 1773868500000,
  "triggerSample": 2000,
  "magSamples": 4000,
  "magRate": 200,
  "audioSamples": 160000,
  "audioRate": 8000,
  "peakMagnetic": 1842,
  "triggerMode": 0,
  "threshold": 50,
  "latitude": 30.267153,
  "longitude": -97.743057,
  "hasAudio": true,
  "magDataSize": 8000,
  "audioDataSize": 40000,
  "deviceSerial": "PS2609A0110",
  "agmSiteNumber": "AGM-001",
  "cursorSample": 2150
}

Errors

• 404 — Event not found

Raw magnetic waveform data as a binary array.

Response

Content-Type: application/octet-stream

• Format: int16[] (little-endian, 2 bytes per sample)
• Sample count matches magSamples from metadata
• Sample rate: 100 Hz (10 ms per sample)

Errors

• 404 — Event not found or file missing

Geophone audio data encoded as IMA ADPCM.

Response

Content-Type: application/octet-stream

• Format: IMA ADPCM (4 bits per sample, 2 samples per byte)
• Original sample rate: 8 kHz
• Decode with standard IMA ADPCM decoder

Errors

• 404 — Event not found or no audio data

Set or clear the cursor position on a recorded event.

Request Body

{"sample": 2150}

Set to null to clear: {"sample": null}

Response

{"ok": true}

Force rebuild of the event manifest from disk. Use after manual file operations.

Response

Same format as GET /api/v1/events.

Delete a single event.

Response

{"status": "ok"}

Delete all events in the active job.

Response

{"status": "ok"}

List all jobs grouped by client, with the active job indicated.

Response

{
  "active": "Acme_Pipeline/Run-042",
  "clients": [
    {
      "client": "Acme_Pipeline",
      "jobs": [
        {
          "jobName": "Run-042",
          "operator": "J. Smith",
          "pipelineSegment": "Segment-A",
          "siteNameTemplate": "AGM-{n:3}",
          "notes": "",
          "createdAt": 1773782400,
          "siteNameCounter": 4
        }
      ]
    }
  ]
}

Create a new job. Becomes the active job by default.

Request Body

{
  "client": "Acme Pipeline",
  "jobName": "Run-043",
  "operator": "J. Smith",
  "pipelineSegment": "Segment-B",
  "siteNameTemplate": "AGM-{n:3}",
  "notes": "",
  "setActive": true
}

Response

{
  "status": "ok",
  "clientDir": "Acme_Pipeline",
  "jobDir": "Run-043"
}

Update job metadata. All fields are optional—only provided fields are changed.

Request Body

{
  "operator": "A. Jones",
  "notes": "Updated notes"
}

Response

{"status": "ok"}

Errors

• 404 — Job not found

Switch the active job. New events will be recorded into this job.

Response

{"status": "ok"}

Errors

• 404 — Job not found

Delete a job and all its events. Cannot delete the currently active job.

Response

{"status": "ok"}

Errors

• 404 — Job not found

Stream the entire job as a ZIP archive.

Response

Content-Type: application/zip

The archive contains:

• job.json — Job metadata
• manifest.json — Full event manifest
• {id}.json — Per-event metadata
• {id}.mag — Binary magnetic waveform (int16[])
• {id}.audio — Binary ADPCM audio (if available)

Errors

• 404 — Job not found

GPS receiver status, movement-aware duty cycling, EASY ephemeris, fix quality, and position (when a fix is available).

Response (with fix)

{
  "gps": {
    "timeSynced": true,
    "fix": true,
    "fixQuality": 1,
    "satellites": 7,
    "hdop": 1.2,
    "duty": "rest",
    "dutyEnabled": true,
    "fixAgeS": 91,
    "dutyStatus": {
      "state": "rest",
      "enabled": true,
      "movementAware": true,
      "relocating": false,
      "orientationKnown": true,
      "upright": true,
      "quietForS": 184,
      "nextWakeS": 209,
      "qualityQualified": true,
      "qualityFallback": false,
      "qualityStreak": 3,
      "qualityRequired": 3,
      "minSatellites": 5,
      "maxHdop": 3.0,
      "quietRequiredS": 15,
      "navSeen": true,
      "lastNavAgeS": 1,
      "recoveryPhase": "idle",
      "wakeReason": "scheduled",
      "wakeAttempts": 3,
      "hotRestarts": 0,
      "faultCount": 0,
      "fallbackContinuous": false
    },
    "easy": {
      "state": "enabled",
      "known": true,
      "enabled": true,
      "predictionDays": 3
    },
    "lat": 30.267153,
    "lon": -97.743057,
    "altitude": 149.20,
    "speedKnots": 0.04,
    "speedMps": 0.0206,
    "utcEpochMs": 1773868800000
  }
}

Response (no fix)

{
  "gps": {
    "timeSynced": false,
    "fix": false,
    "fixQuality": 0,
    "satellites": 0,
    "hdop": 0.0,
    "duty": "acquire",
    "dutyEnabled": true
  }
}

WiFi mode, coexist state, access point info, and station connection status. internet is true when the device has proven connectivity (cloud session or completed time sync); cloud is true while the AWS IoT MQTT session is live. mdnsUrl is the address where this interface is reachable from either network.

Response (station connected)

{
  "wifi": {
    "mode": "AP+STA",
    "coexist": true,
    "internet": true,
    "cloud": true,
    "hostname": "pigstick-2001",
    "mdnsUrl": "http://pigstick-2001.local",
    "ap": {
      "ssid": "PigStick-2001",
      "channel": 1,
      "clients": 1
    },
    "sta": {
      "connected": true,
      "enabled": true,
      "pausedForAp": false,
      "reconnectHeld": false,
      "subnetConflict": false,
      "ssid": "FieldOffice",
      "rssi": -52,
      "channel": 1,
      "ip": "192.168.1.105"
    }
  }
}

When the station is disconnected, sta instead carries lastDisconnectReason (e.g. "NO_AP_FOUND", "AUTH_FAIL") when one is known. subnetConflict is true when the uplink lease collides with the access point's own 10.0.0.0/24 subnet. reconnectHeld means the station link is being kept alive while reconnect/scan activity is held for an access-point client.

Enable or disable Starlink / Local Network Mode (simultaneous AP + station operation with the interface and cloud served over the uplink network). Persisted in NVS; takes effect on the next restart. Requires at least one user-saved network to become active.

Request Body

{"enabled": true}

Response

{"success": true, "coexist": true, "rebootRequired": true}

Scan for available WiFi networks. This is a blocking operation that takes a few seconds.

Response

{
  "networks": [
    {
      "ssid": "FieldOffice",
      "rssi": -52,
      "secure": true,
      "channel": 1,
      "bssid": "c0:6f:98:9b:58:c6"
    },
    {
      "ssid": "OpenNetwork",
      "rssi": -78,
      "secure": false,
      "channel": 11,
      "bssid": "aa:bb:cc:dd:ee:ff"
    }
  ]
}

List saved WiFi networks. Passwords are not returned. factory:true marks the built-in factory/bench network, which the interface hides outside admin mode. channel/bssid are the cached identity from the last successful connection (used for fast reconnects and access-point channel pinning), 0/null when unknown.

Response

{
  "networks": [
    {
      "ssid": "FieldOffice",
      "priority": 0,
      "channel": 1,
      "factory": false,
      "bssid": "c0:6f:98:9b:58:c6"
    }
  ]
}

Save a WiFi network. The device stores up to 5 networks.

Request Body

{
  "ssid": "FieldOffice-5G",
  "password": "secretpass"
}

Response

{"success": true}

Errors

• 400 — Missing or empty SSID
• 400 — Maximum networks reached (5)

Delete a saved WiFi network.

Request Body

{"ssid": "FieldOffice-5G"}

Response

{"success": true}

Errors

• 400 — Missing or empty SSID
• 404 — Network not found

Firmware version and storage statistics.

Response

{
  "system": {
    "firmware": "2.2.72",
    "storage": {
      "total": 10379264,
      "used": 1245184,
      "free": 9134080
    },
    "uptime": 3621
  }
}

Returns bounded, in-memory connection ownership evidence: HTTP and stream registry counts, active viewer UUIDs and fd generations, close-cause counters, and the 16 most recent lifecycle events. The history resets when the device restarts.

Add the same page-scoped ?viewer=<uuid> value to the audio, magnetic, and control WebSocket URLs so one viewer's sockets can be correlated.

Restart the device. The restart occurs after a 1-second delay to allow the response to be sent.

Response

{
  "restart": {
    "scheduled": true,
    "delayMs": 1000
  }
}

Check for software updates. Behavior depends on connectivity:

• Starlink / Local Network Mode with the station connected: the check runs in place over the live network link. No restart; the response reports "rebooting": false. The manifest is fetched, the update hint refreshed, and any queued update job is requested immediately (a manual check also overrides the wait-for-idle rule for the next 10 minutes). Poll /api/v1/service/status for the result.
• Otherwise: the legacy flow. The device schedules a service-mode restart, briefly leaves its own network to reach a saved network, installs any assigned update, and restarts back to normal operation. The response reports "rebooting": true and the device goes offline shortly after.

Response (in-place check)

{"service": {"scheduled": true, "mode": "checkUpdates", "rebooting": false, "online": true}}

Response (restart flow)

{"service": {"scheduled": true, "mode": "checkUpdates", "rebooting": true, "delayMs": 1500}}

Errors

• 409 — No saved WiFi network

Service-mode state and the most recent update-check result. updateHint.status is checking, available, none, skipped, or error; the interface polls this after an in-place check.

Response

{
  "service": {
    "active": false,
    "request": 0,
    "lastStatus": "complete",
    "lastDetail": "Checking for updates over WiFi network",
    "updateHint": {
      "status": "none",
      "detail": "No update indicated by fleet manifest",
      "available": false,
      "firmware": false,
      "app": false,
      "firmwareVersion": "2.2.72",
      "appVersion": "2.2.95",
      "checkedBootMs": 108721
    }
  }
}

Lightweight OTA phase and byte progress for polling while install activity temporarily stops live streams. The active flag remains true during post-reboot validation.

Response

{"ota":{"phase":"downloading","component":"firmware","downloaded":512000,"total":1024000,"percent":50,"active":true}}

Accept an update job currently advertised by updateHint. Stale or arbitrary job IDs are rejected.

Request Body

{"jobId":"pigstick-update-2-2-72-20260726"}

Run AWS IoT fleet provisioning with a valid PigStick serial number. Intended for manufacturing and authorized service workflows.

Set the device serial without cloud provisioning. A restart is required before the new identity and WiFi name are fully applied.

Report the connected browser app version for device status and cloud shadow reporting.

Request Body

{"version":"2.2.95"}

Real-time geophone audio stream.

Binary Frames (device → client)

• Format: 12-byte v2 shared-stream header followed by one independently decodable IMA ADPCM block
• Sample rate: 8 kHz
• Frame size: 256 samples, normally 144 bytes including the header
• Rate: ~31.25 frames/second

Text Commands (client → device)

Send as JSON text frame, e.g.: {"preamp": 4.0}

Real-time magnetic sensor stream with JSON event notifications.

Binary Frames (device → client)

Format 8 frames contain a 12-byte v2 shared-stream header, aligned MFL and ELF-envelope int16 arrays, and a final format byte.

• Sample rate: 100 Hz
• Normally 8 samples per channel and 45 bytes total

JSON Event Frames (device → client)

Text frames carry real-time event notifications:

Device-authoritative shared settings with state broadcasts and acknowledged get/set commands.

Examples

{"type":"set","id":102,"set":{"preamp":64,"threshold":55}}
{"type":"ack","id":102,"ok":true,"rev":43,"state":{"preamp":64,"filterHp":0,"filterLp":500,"armed":true,"threshold":55,"magMode":"both"}}