/capture

The capture service allows collecting waveform data for configured input channels.

GET /capture&i returns information about the channels for which waveform data can be captured. The returned object might look like this:

{
  "channels": {
    "0": {"name": "L1", "unit": "V"},
    "1": {"name": "L2", "unit": "V"},
    "4": {"name": "S1", "unit": "A"}
    }
}

This response indicates that three channels are available. The meter-internal channel numbers are 0, 1, and 4. As the name values indicate, those channels correspond to meter inputs L1, L2, and S1, respectively. The first two channels return samples as volts (V) and the third returns samples as amperes (A).

GET /capture?n&d=1e-3&c=0&c=4 initiates a capture for 1ms of samples on channels 0 and 4 and returns a cookie (token) to be used to retrieve the capture samples. The response for this request might look like this:

{"state": "armed", "cookie": 1875353535}

State armed indicates that the meter successfully processed the capture request and is waiting for the trigger to occur. Cookie 1875353535 is a random integer to be used when retrieving the sampled data, as shown next.

GET /capture?n=1875353535 can now be used to fetch the samples. The response might look as shown below:

  {
    "state": "full", "ts_freq": 1000000, "first_sample": "1619637288.061",
    "ch_mask": [17, 0],
    "r": [
      {"t": 495514564, "d": [135.059]},
      {"t":        82, "d": [-0.0146239]},
      {"t":      1354, "d": [105.454, -0.00731193]}
    ]
  }

State full indicates that the capture buffer is full and therefore the response contains sample values. The frequency of the counter used to generate the timestamps is 1MHz ("ts_freq": 1000000) and the realtime Unix timestamp of the first sample is 28 April 2021, 19:14:48 UTC (first_sample": "1619637288.061"). The ch_mask member is an array of 32-bit integers. If a bit is set in this mask, data for that channel is included in the response. In our case, the channel mask has only bits 0 and 4 set in the first integer (17), indicating that channels 0 and 4 are contained in the sampled data (in order from smallest to largest channel numbers). The timestamp t of the first sample is 495514564 and the subsequent samples were acquired 82 and 1354 timestamp ticks after the corresponding previous sample. Thus, the reconstructed sample values for the channels are:

Note how the sample values are returned strictly in order from lowest number to highest numbered channel: 0, 4, 0, 4. Also note how there is a separate entry in the result array r for each unique timestamp. Each data array (d) may have just a single entry or multiple entries if there are multiple sample values with the same timestamp.

A Python program illustrating the use of this service can be found here. This program takes advantage of class egauge.webapi.device.Capture to handle the details of encoding the HTTP requests and decoding the responses.