Integration JSON

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.

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

JSON

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

Calibration JSON

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:

JSON

[
  {
    "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:

JSON

[
  {
    "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.

JSON

[
  {
    "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.

JSON

[
  {
    "eID": "STABSPECTRO_xxxx",
    "vT": 1623330083308,
    "v": {
      "Realtime": 0.999,
      "Livetime": 0.997,
      "Total": 121,
      "Countrate": 121,
      "Cosmics": 0,
      "A1": 0.659999668598175,        // Stabilization parameter
      "Q": 0.409785896539688,          // Stabilization quality indicator
      "StabSpectrum": ["<300_channel_spectrum>"],
      "K40": 158.039154052734,         // Activity concentration in Bq/kg
      "sK40": 226.527160644531,        // Uncertainty in K40
      "U238": 7.76706838607788,
      "sU238": 36.8515777587891,
      "Th232": 17.5619468688965,
      "sTh232": 30.5838088989258,
      "Cs137": -3.49871563911438,
      "sCs137": 21.3017673492432
    }
  }
]

GPS Data

JSON

[
  {
    "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

JSON

[
  {
    "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.

JSON

[
  {
    "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.1572,
      "Height": 58.983
    }
  }
]

External RS-232 Data

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

JSON

[
  {
    "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.

JSON

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