Advanced Probes Documentation

[nebhead]

Advanced Probes

Advanced Probes updates was introduced to solve some basic problems that PiFire currently has, and to allow for much more options for configurations in the future.

The former ADC module has been replaced by probes modules.

The structure is as follows:

The 'probe_complex'

PiFire creates a 'probe_complex' object of the ProbesMain class (from probes_main.py), which is the nexus of all probe input.

When the probe_complex object initializes, it creates a list of probe device objects (defined in settings.json > probe_settings > probe_map > probe_devices). Each of these device objects is an instantiation of one of the probe_*.py device types.

When pifire wants to get data from the probe sensor devices, it will use the probe_complex.read_probes() function. This will return a data structure that looks like the following:

{
  "primary" : {
    "Grill" : 165
  },
  "food" : {
    "Probe1" : 100,
    "Probe2" : 0
  },
  "aux" : {
    "Grill2" : 0
  }, 
  "tr" : {
    "Grill" : 1610, 
    "Probe1" : 130458,
    "Probe2" : 0
  }
}

The primary probe input, is the probe identified by by PiFire to be the main probe for grill input. This is the probe used for hold temperatures, safety, re-ignition, etc.

The food probe inputs are inputs that can be used for tracking food temperatures, setting notifications, or recipe steps.

The aux (or auxiliary) probes are probes that are tracked by PiFire, but not shown in the WebUI, nor are used for notifications. These can be used to silently gather data, or can be used by virtual probes.

The tr values, are the calculated probe resistance values, for ADC calculations. This is used by the front-end WebUI to tune new probes.

Probe Devices

Probe Devices are physical devices, like the ADS1115 or MAX31865 that have probe inputs/ports which can be read. Each probe device is loaded as an object into the probe complex device list.

Devices are supported using the probes_*.py files and should inherit the ProbeInterface class from probes_base.py.

These device objects can be configured by adding a device definition to the settings.json file in probe_settings > probe_map > probe_devices.

Example Device Definition:

        {
          "config": {},
          "device": "Prototype",
          "module": "prototype",
          "ports": [
            "ADC0",
            "ADC1",
            "ADC2",
            "ADC3"
          ]
        }

In the example above, the prototype module will be loaded where the filename is probes_[module].py. The 'device' field should be a unique name that only contains alphanumeric characters. This device name is how probes will be mapped back to a particular device object. The 'ports' field indicates ports available on the device. The 'config' field is used to define any device specific settings.

When the probe_complex is initialized, it will consume any devices in the settings.json probe_map and configure them per the definitions.

Probes

The probes themselves are then mapped to devices, as defined in the settings.json file in probe_settings > probe_map > probe_info.

Example Probe Definition:

        {
          "device": "Prototype",
          "enabled": true,
          "label": "Grill",
          "name": "Grill",
          "port": "ADC0",
          "profile": {
            "A": 0.04136906456,
            "B": -0.00677987613,
            "C": 2.760294589e-05,
            "Rd": 10000,
            "Vs": 3.28,
            "id": "PT-1000-OEM",
            "name": "PT-1000-Grill-Probe-OEM"
          },
          "type": "Primary"
        },

In the example above, the 'device' maps back to the Prototype device we defined earlier. The 'enabled' flag is set (which is currently ignored by PiFire). The 'label' is a unique identifier that contains only alphanumeric characters, which is used by PiFire to identify the specific probe in output data. The 'name' is a human readable / formatted name/identifier used in the WebUI and cookfile. The 'port' maps back to the device > port that it is associated with. This doesn't need to be unique, and several probes could potentially share the same device and port. The 'profile' is a copy of the profile that is being used from settings.json probe_settings > probe_profiles. Lastly, the 'type' can be:

• 'Primary' : for the primary probe (previously known as the Grill probe). There can only be one Primary probed defined. PiFire will behave unexpectedly if more than one Primary probe is defined.
• 'Food' : for a food probe, which will be displayed in the WebUI.
• 'Aux' : for an auxiliary probe, which will not be displayed in the WebUI, but will be tracked in the history database.

History Data Structure

The history data structure has been redesigned to store the relevant probe data from the probe_complex, along with the set point for the primary probe and the notification targets. In addition, extended data can be stored for debug/experimental purposes.

History is stored in the Redis database as an ordered list. Each list item / line item, is all the data collected at that specific time time organized by probe and type.

When the read_history function is called, it will return a list of dictionaries formatted like the below example:

[
  {
    "T": 1674255152444,
    "P": {
      "Grill": 466
    },
    "PSP": 0, 
    "F": {
      "Probe1": 208,
      "Probe2": 206
    },
    "NT": {
      "Grill": 0,
      "Probe1": 0,
      "Probe2": 0
    },
    "AUX": {},
    "EXD": {
      "CR": 0.1875,
      "RCR": 0.1875
    }
  },
  ...
]

Each item in the list is broken into sections:

• 'T' - Timestamp of when the data was sampled
• 'P' - Dictionary of Primary probe temperatures formatted: 'label' : temperature
  • NOTE: Currently only one primary probe is supported by PiFire, so there should only be one label/value pair.
• 'PSP' - Primary Set Point Temperature
• 'F' - Dictionary of Food probe temperatures formatted: 'label' : temperature
• 'NT' - Dictionary of Notification Targets, used to track target for notification for each probe. This should include both food probes and the primary probe. This is formatted: 'label' : temperature
• 'AUX' - Dictionary of Auxiliary probe temperatures formatted: 'label' : temperature
  • NOTE - Auxiliary probes are not intended to be displayed on the graph and are to be used by virtual probes, or are just for capturing extra data.
• 'EXD' - Dictionary of Extended Data values. This can contain any number of key : value pairs, and can be used to store extra data used for debug, etc.

Virtual Devices

Virtual devices are special devices that can be used to perform some kind of math on a set of other probe ports. For example, if you have an ADS1115 device with four ports, you might want to average the ADC0 and ADC4 port together and use that for your primary probe. You could assign the ADS1115 Port 0 & 4 to the Virtual Average device, and then configure a primary probe to use that Virtual Average device's port.

Currently, there are a few virtual devices to choose from:

• virtual_average - obtains the average temperature from a list of ports
• virtual_highest - obtains the highest temperature from a list of ports
• virtual_lowest - obtains the lowest temperature from a list of ports
• virtual_median - obtains the median temperature from a list of ports

It may even be possible to 'stack' virtual ports, though it hasn't be tested. Using a virtual port to feed into another virtual port.

Changing the Configuration

It is possible to update the probe names and probe profiles while the system is operational. However, re-configuring devices or adding or removing ports will require a server restart.