Data Integration — JSON Format

All sensor data collected by Medusa gamma-ray spectrometers is stored and streamed in JSON format. This chapter describes the structure of those JSON strings.

Data can be received in two ways:

• Onboard storage — JSON files are written to the detector and can be downloaded via the Projects page
• Live stream — data can be streamed in real time over UDP or RS-232 (see Settings → Communication)

An example data file exampleData(v2).json can be downloaded from the Projects page in the mDOS interface.

Info

Note: In the code blocks on this page, text in <> brackets explains a concept, and some lines have comments preceded by //. These are not valid JSON — they are used here for clarity only.

---

System JSON Strings

System JSON strings describe the detector and its calibration. They appear once per file, at the start.

System JSON

[
  {
    "Hostname": "MS350-00xx",
    "MedusaID": "MS-350.00xx",
    "CarrierVersion": "2.0",
    "PSUVersion": "2.0"
  }
]

Calibration JSON

[
  {
    "mcf_name": "ms350-00xx_3x3csi_xx-xx-20xx_kuthcs.a2320",
    "encrypted_mcf_string": "<Encrypted_JSON_STRING>"
  }
]

---

General Sensor Data Structure

All JSON strings containing measurement data share the same outer structure:

[
  {
    "eID": "<sensorType>_<SensorSerial>",   // Sensor type identifier and serial number
    "v": {},                                // Measurement values, unique per sensor type
    "vT": <timestamp>                       // Unix timestamp in milliseconds since Jan 1st 1970
  }
]

Each sensor type has an accompanying meta file describing its fields:

[
  {
    "objectVersion": "1.0",
    "eID": "<eID>",
    "classID": "<name>",
    "sensorConfig": { "<Sensor configuration>" },
    "sensorMeasures": [
      {
        "measureLabel": "<label>",
        "measureDescriptor": "<description>",
        "measureType": "<array/number/string>",
        "measureUnit": "<units>",
        "measureUnitEx": "<alt_units>",
        "measureLow": 0,
        "measureHigh": 4294967295,
        "measureResolution": 1,
        "measureAccuracy": 1,
        "array_size": "<size>",
        "synchronisation_method": "<0,1,2>"
      }
    ]
  }
]

---

Spectrometer Data

Raw Spectrum

Raw spectrum data is measured by the onboard Multi-Channel Analyser (MCA). It contains integer counts per channel.

[
  {
    "eID": "SPECTRO_xxxx",
    "vT": 1623330081307,
    "v": {
      "Realtime": 1.001,
      "Livetime": 0.999,
      "Spectrum": ["<array>"],
      "Total": 108,
      "Countrate": 108,
      "Cosmics": 0
    }
  }
]

Stabilized Spectrum

A stabilized spectrum is a raw spectrum converted to an energy scale. It consists of 300 channels and can contain fractional counts.

Note: The spectrometer must collect at least 10,000 counts in the 400–3,000 keV range before it can calculate a valid stabilization. Depending on the crystal size, this may take several minutes after startup.

[
  {
    "eID": "STABSPECTRO_xxxx",
    "vT": 1623330083308,
    "v": {
      "Realtime": 0.999,
      "Livetime": 0.997,
      "Total": 121,
      "Countrate": 121,
      "Cosmics": 0,
      "A1": 0.659,            // Stabilization parameter
      "Q": 0.409,             // Stabilization quality indicator
      "StabSpectrum": ["<300_channel_spectrum>"],
      "K40": 158.039,         // Activity concentration in Bq/kg
      "sK40": 226.527,        // Uncertainty in K40
      "U238": 7.767,
      "sU238": 36.851,
      "Th232": 17.561,
      "sTh232": 30.583,
      "Cs137": -3.498,
      "sCs137": 21.301
    }
  }
]

---

GPS Data

[
  {
    "eID": "GPS_0006",
    "vT": 1623330083893,
    "v": {
      "Date": 1623330083000,
      "Lat": 53.0107648,
      "Lon": 7.0139993,
      "Height": 58.983,
      "HeightMSL": 13.299,
      "hAcc": 0.519,
      "vAcc": 0.851,
      "gpsFix": 3,
      "rtkFix": 0,
      "noSat": 30,
      "pDOP": 0.92,
      "gSpeed": 8.36,
      "sAcc": 1.55,
      "Heading": 0.0,
      "cAcc": 5.9975
    }
  }
]

Field	Description	Unit
Date	Date from the GPS	Milliseconds since 1970
Lat	Latitude	degrees
Lon	Longitude	degrees
Height	Altitude above the ground	metres
HeightMSL	Height above mean sea level	metres
hAcc	Horizontal accuracy estimate	metres
vAcc	Vertical accuracy estimate	metres
gpsFix	GPS fix type: 0 = no fix, 1 = dead reckoning only, 2 = 2D-fix, 3 = 3D-fix	—
rtkFix	RTK solution: 0 = no, 1 = float solution, 2 = fixed solution	—
noSat	Number of satellites used in fix. A value of -1 indicates the GPS antenna is not connected.	—
pDOP	Positional dilution of precision	—
gSpeed	Ground speed (2D)	m/s
sAcc	Speed accuracy estimate	m/s
Heading	Heading of motion (2D)	degrees
cAcc	Heading accuracy estimate	degrees

---

PTH Data

[
  {
    "eID": "PTH_0006",
    "vT": 1623330083950,
    "v": {
      "Press": 1017.2866,
      "Temp": 30.71,
      "Hum": 27.75
    }
  }
]

Field	Description	Unit
Press	Air pressure	hPa
Temp	Temperature	°C
Hum	Relative humidity	%

---

Synchronized Data

The detector synchronizes all sensor data into a single JSON string. The stabilized spectrum is used as the basis; GPS and PTH readings are interpolated to the spectrometer's timestamp. The SYNC JSON can be used directly for georeferenced processing, without needing a separate post-processing step.

[
  {
    "eID": "SYNC_xxxx",
    "vT": 1675441175625,
    "v": {
      "Realtime": 3.003,
      "Livetime": 2.991,
      "Total": 2210,
      "Countrate": 724,
      "Cosmics": 2,
      "A1": 0.647,
      "Q": 0.505,
      "StabSpectrum": ["<300_channel_spectrum>"],
      "K40": 1237.255,
      "sK40": 175.886,
      "U238": 76.274,
      "sU238": 27.237,
      "Th232": 129.369,
      "sTh232": 19.725,
      "Cs137": 0.246,
      "sCs137": 18.605,
      "Dose": 0.116,
      "Lat": 53.0107648,
      "Lon": 7.0139993,
      "Date": 1584835625503,
      "Height": 58.983
    }
  }
]

---

External RS-232 Data

Text data received over the RS-232 port is stored as follows:

[
  {
    "eID": "TXT_external",
    "vT": 1623330083950,
    "v": { "<A text line received over the RS-232 port>" }
  }
]

---

Multi-Crystal Systems

When the detector contains multiple crystals, the raw spectrum JSON contains an array of spectra — one per crystal. A crystal tagged with "type": "upward" is an upward-looking detector.

All spectra not tagged as upward are stabilized and summed. The summed spectrum is then analysed as a single stabilized spectrum.

[
  {
    "eID": "SPECTRO_sum",
    "vT": 1623330081307,
    "v": {
      "[<array of raw spectra>]"
    }
  }
]