Module architecture and data formats - MONICA-Project/sound-heat-map GitHub Wiki

The sound heat map module is initializing itself in the following steps (all-caps variables are configuration parameters set as environment variables):

1. Registration as a service with LinkSmart node

For each weighting in WEIGHTINGS the module sends a POST request to the OGC service catalogue at CATALOGUE_URL/SearchOrCreateOGCDataStreamId with the payload

msg = {
	"externalId": f"SoundHeatMap/{SHM_ID}/{weighting}",
	"metadata": "SoundHeatMapGenerator",
	"sensorType": f"SoundHeatMap/L{weighting}eq",
	"unitOfMeasurement": f"Sound Heat Map with {weighting}-weighted values.",
	"fixedLatitude": 0,
	"fixedLongitude": 0,
}

This registers a separate sound-heat-map for each weighting function. The MQTT broker and the MQTT topic for each sound-heat-map datastream is taken from the response to these POST requests.

2. Querying the OGC SensorThing server for available sound-level-meter datastreams

The OGC SensorThing instance at GOST_URL is queried for the @iot.id of the ObservedProperty with name CPBLZeq using a GET request to GOST_URL/ObservedProperties?$filter=equals(name, 'CPBLZeq'). These are the sound level meter measurements in third octave bands with Z-weighting.
Using this @iot.id, all Datastreams that report this property and their ids are found with a GET request to GOST_URL/ObservedProperties({@iot.id})/Datastreams?$filter=FILTER_MICS.

This step is repeated every UPDATE_DATASTREAMS_PERIODE seconds to update the list of sound-level-meter datastreams.

3. Subscribing to the relevant MQTT topics

The module connects to the MQTT broker via the address received in step 1. For each sound-level-meter datastream found in step 2 the module

checks if the positions of the sensor is inside the sound heat map area specified by POLYGON_AREA, if so
subscribes to the corresponding MQTT topic MQTT_BROKER_PREFIX/Datastream({@iot.id})/Observations.

4. Creating sound heat maps

Data received by listening to the MQTT messages is cached. Every NEW_MAP_PERIODE a new sound heat map for each weighting in WEIGHTINGS is published via the corresponding MQTT topics received from the OGC service catalogue in step 1.

The data published via MQTT has the following form

{
  "phenomenonTime": "2020-02-18T16:38:30Z",  // same as endtime
  "result": {
    "bandFrequencies": ["fullband"],         // array of F frequencies at which the sound heat map was computed or single array with value "fullband" if weighting is of form Xfullband
    "cellsize": 0.0005,                      // same as CELLSIZE
    "data": [                                // the sound heat map array with shape (nfreqs, nrows, ncols), if an entry is `null`, then this point would lie outside of POLYGON_AREA and has not been computed.
      [
        [null, null, 61.16170974554575, 61.22001969608816, 62.70934715607899, 66.01747203806102, 62.70656440700863, 66.97022932772084, 66.66681481958487, 67.73455449691062, null, null, null],
        [null, null, 60.57488716873579, 62.43261204100733, 61.44134741111532, 64.38821238338664, 66.59251917412487, 64.17663748240035, 64.6526455193025, 66.10278134127712, 63.7350140509989, null, null],
        [null, null, 61.90804173164053, 61.17774262641568, 62.22038997101653, 63.27194988406403, 63.50109830751148, 65.46191177502888, 64.98906259041819, 68.1908563541645, 66.07297765943252, null, null],
        [null, null, 61.471492081937875, 64.59606500812744, 65.55383263104805, 63.68045096860324, 65.10751685585642, 61.495177837902084, 67.9970695849721, 66.0472870274941, 68.75040364332266, null, null],
        [null, null, 61.33299530772505, 59.42718969729013, 63.406209099101034, 62.945898622829894, 66.06655857145982, 64.93993967386793, 67.29025108188529, 66.53726929043589, 67.90769471211534, null, null],
        [null, null, 61.71108880431568, 61.292408090635874, 63.95105946889689, 60.47826189872282, 65.68086227985198, 64.45489485394404, 68.1899476584932, 68.35392977576414, 69.23450922162417, null, null],
        [null, null, 62.06088767835097, 62.237937389629636, 62.92595134369875, 64.51453802345262, 63.084607719368755, 68.11511206063597, 63.704345495186566, 65.20265990168357, 69.53335472549094, null, null],
        [null, null, 64.13073524224923, 65.7712884395566, 64.84254683675002, 64.0215061775581, 66.21783512464005, 64.69763859977394, 66.36622567593909, 67.66853798926881, 69.60026866977414, null, null],
        [null, null, 65.73325710735539, 67.09797086511603, 67.05340991029973, 68.02526324722656, 69.7526523035327, 69.17789762284404, 70.79593727076941, 71.8910671596519, 73.61362129756783, null, null],
        [null, 61.61761725736399, 64.39439860190322, 64.30233209535297, 63.908866605858364, 65.69411080253984, 65.95403268483153, 65.22997376039055, 67.99477042540401, 67.96715938634813, 69.90610842641888, null, null],
        [null, 61.68508645086828, 61.966267753141636, 60.733838565194, 64.07783379510245, 63.803539554562654, 63.93007557455964, 63.89152201843341, 65.38532003182807, 67.4476111799713, 70.70100268326378, 73.75537434949113, null],
        [null, 59.4268041190739, 59.81078871062284, 60.36282087807929, 63.41792364196741, 62.447369864747486, 62.437775471809694, 65.02580586443582, 67.08448020772965, 65.86342677531039, 64.88687978758213, 70.24559781939993, null],
        [null, 60.96136014125432, 58.913236764819, 60.278772985708216, 62.71476368524545, 61.71615215846377, 64.61857106493038, 62.807027096417, 66.99743098538227, 67.16244983649348, 65.6324135780294, 71.44426971992372, null],
        [null, 58.53777391130066, 62.92886004933113, 59.981706467112524, 65.45899956650993, 63.472676095936144, 60.95161578755554, 63.13164422033531, 63.570454687620234, 64.28143694046425, 68.52750846432792, 69.67163427094465, null],
        [null, 58.17600059630678, 61.81502496551806, 62.69780037837661, 60.694343234260856, 63.551762082860385, 59.923942169100386, 63.86560999724833, 62.790089988229994, 66.99762166680833, 66.68328190947831, 66.76297640024683, null],
        [null, 60.114544990938725, 59.498002957030984, 60.75236622777662, 61.10537421530614, 60.46328845581673, 63.97300617298519, 61.341619057395604, 65.08262497268208, 66.63478104622632, 65.60135465348668, 65.3327172988148, null],
        [null, 57.290260222770144, 59.970569192789796, 60.83801231415339, 61.771030463288426, 62.29037546249016, 59.62865972626392, 64.2174464802367, 64.95978531846262, 63.48289140706635, 63.40874539456, 63.69937276670644, null],
        [null, 61.463444287788896, 58.53685247818876, 61.98314279023441, 60.698414785449295, 60.23017478355818, 62.83523394708821, 63.17478033107683, 61.81339559424812, 62.214675883925096, 63.77339407936358, 61.67857753733094, null],
      ],
    ],
    "endtime": "2020-02-18T16:38:30",        // starttime and endtime specify time span over which data was averaged  
    "input_positions": {                     // These are the same as POLYGON_AREA, SOURCES, WALLS with additional positions of the sound level meters (slm_latlon)
      "shm_area": [                          // The polgyon that defines the sound heat map area, same as POLYGON_AREA
        [45.056, 45.06, 45.061, 45.055],
        [7.676, 7.676, 7.685, 7.685],
      ],
      "slm_latlon": [                        // Positions of sound level meters that were used for computation of this map
        [45.05829, 45.057837, 45.059172, 45.058518],
        [7.67847, 7.681555, 7.678986, 7.678854],
      ],
      "sources_latlon": [                    // The source positions in the sound propagation model, same as SOURCES
        [45.0619, 45.0619, 45.0619],
        [7.6801, 7.68, 7.68005],
      ],
      "walls_latlon": [                      // The positions of reflecting walls in the sound propagation modle, same as WALLS
        [
          [45.055],
          [45.0619],
        ],
        [
          [7.675],
          [7.675],
        ],
      ],
    },
    "lat_0": 45.055,                          // positions in lat/lon of lowest left point of data grid 
    "lon_0": 7.676,                           // can be used together with cellsize, nrow and ncols to compute positions grid of the data
    "ncols": 13,
    "nfreq": 1,
    "nrow": 18,
    "starttime": "2020-02-18T16:38:10",
    "timeStamp": "2020-02-18T16:38:30",      // same as endtime
    "unit": "SPL dB Cfullband",              // the unit of the sound heat map data
  },
  "resultTime": "2020-02-18T16:38:41.561359Z",  // Time when this sound heat map was computed
}

The grid of positions has the following shape, where it is assumed that the vertical lines are oriented toward North while the horizontal lines toward East.