Probe Groups

Problem

Some settings supported by a device may apply to specific probes, rather than a device instance as a whole. The current sr_config_{get,set,list} API does not define a way to represent this.

A representation of this information is needed in the API so that frontends can provide an appropriate UI to the user, and so that configuration requests can be made unambiguously to devices with probe-specific settings.

Use Cases

1. Settings that apply for each available individual probe.
   • The Rigol DS1052E has two analog probes, CH1 and CH2. Volts per division can be set individually for each.
2. Settings that apply only for probes of a given type.
   • The Rigol DS1102D has two analog probes, and 16 digital probes. Volts per division can be set only for the analog probes. Threshold voltage can be set only for the digital probes.
3. Settings that apply only for groups of probes of the same type.
   • The PicoScope 2205 has 16 digital probes in two groups of 8. Threshold voltage can be set only for each group of 8.

Previous Ideas

1. Use the existing API, but where settings are per-probe, use a GVariant array of the values for each probe, rather than a single GVariant value.
   • This does not address use case 3.
2. Use the existing API, but where settings are per-probe, use a GVariant array of (probes, value) tuples, rather than a single GVariant value.
   • This is possible, but creates a lot of work. Probes could not be specified by pointer in the GVariant, so would have to be passed by name. In a sr_config_set call, the driver would then have to match the names to some internal data structure.
   • It also loads a lot of structure into a GVariant value that was originally conceived as being merely a simple value whose type would vary between configuration settings according to the nature of each setting.
   • Every frontend, driver and binding would have to implement the code required to pack and unpack these GVariant structures.

Proposal

Concept

• Modify the API to include an explicit "probe group" data type, which can be passed to sr_config_{get,set,list} to address a specific group of probes.
• Provide a way for frontends to get the available probe groups for a device.

API

Define the following structure for a probe group:

struct sr_probe_group {
    /* List of sr_probe structs. */
    GSList *probes;
    /* Private data for driver use. */
    void *data;
};

Modify the signatures for sr_config_{get,set,list} as follows:

SR_API int sr_config_get(const struct sr_dev_driver *driver,
     const struct sr_dev_inst *sdi,
     const struct sr_probe_group *probe_group,
     int key, GVariant **data);

SR_API int sr_config_set(const struct sr_dev_inst *sdi,
     const struct sr_probe_group *probe_group,
     int key, GVariant *data);

SR_API int sr_config_list(const struct sr_dev_driver *driver,
     const struct sr_dev_inst *sdi,
     const struct sr_probe_group *probe_group,
     int key, GVariant **data);

Modify the signatures in struct sr_dev_driver as follows:

int (*config_get) (int id, GVariant **data,
     const struct sr_dev_inst *sdi,
     const struct sr_probe_group *probe_group);

int (*config_set) (int id, GVariant *data,
     const struct sr_dev_inst *sdi,
     const struct sr_probe_group *probe_group);

int (*config_list) (int info_id, GVariant **data,
     const struct sr_dev_inst *sdi,
     const struct sr_probe_group *probe_group);

In all the above functions, passing NULL for probe_group would have the same meaning as the current function without the probe_group parameter. Passing a probe group would implement the function for that specific group of probes.

The available probe groups are defined by the driver.

Initially, it is proposed to add a GSList *probe_groups field to struct sr_dev_inst to list the probe groups for a device. In all current use cases, these groups are static.

In future we may encounter devices in which certain settings are grouped in ways that change dynamically. In this case, we will need to replace this field with a new API call that retrieves the currently applicable groups.

Implementation

Steps 1-7 are to be done in a probe_groups branch on each project repository.

1. Implement the above API change for libsigrok.
   • See commit at:
     https://github.com/martinling/libsigrok/commit/fc59c9a9433857600eccb02b54ebbbf34a7449ed
   • After this change, all drivers can be considered to implement device-wide settings only and all devices have an empty list of probe groups.
2. Patch clients to work with new API.
   • Initially, this can be done by simply adding a NULL probe_group parameter to all sr_config_{get,set,list} calls, and changing to the reordered parameters.
   • sigrok-cli
   • pulseview
3. Implement probe groups in drivers.
   • Rigol DS1xx2
4. Implement probe group support in clients.
   • Python bindings
   • sigrok-cli
   • pulseview
5. Testing and evaluation.
6. Decide whether to move forward, or revise the concept/implementation.
7. Update documentation.
8. Merge into master.