tlbmc/g3doc/onboarding_npis/fru_collector_module.md - gbmcweb - Git at Google

 # Onboarding NPIs to Fru Collector Module

 go/tlbmc-onboarding-npis

 <!--*
 # Document freshness: For more information, see go/fresh-source.
 freshness: { owner: 'tlbmc-dev' reviewed: '2025-10-13' }
 *-->

 This document outlines the additions necessary to Entity-Manager (EM) JSON
 configuration files to enable fru collector module on an NPI.
 [Entity-Manager](https://github.com/openbmc/entity-manager) provides mappings
 from hardware components to software components within a system, these mappings
 are managed through EM configuration files as described here.

 Note: tlBMC requires only additions to existing EM config files, no deletions or
 modifications of existing properties should occur. This allows tlBMC to be
 backward compatible with existing bmcweb without conflicting behavior. Original
 design doc can be viewed at go/tlbmc-data-completeness

 Tip: Existing daemons, e.g. PSU sensors, will still coexist if not disabled
 explicitly. Whether these should be configured depends on the use case. If the
 sensor is only used in telemetry reporting not control, e.g. PID, tlBMC can
 fully replace existing daemons. In this case, see the section **SkipDbusRead
 Property** which describes how to disable sensor polling over dbus to
 significantly improve CPU utilization.

 ## Prerequisites

 The tlBMC FRU Collector Module must be enabled for your platform in
 `tlbmc_config_bundle.textproto`. If it is not enabled, tlBMC will not collect
 FRU data regardless of EM configuration.
 See `tlbmc_config_bundle.textproto` in tlbmc source.

 [TOC]

 ## Chassis

 ### ProbeV2

 The addition of the ProbeV2 field makes the config detectable by tlBMC. The
 value of the `IpmiFru` JSON within the ProbeV2 field corresponds with the
 existing `Probe` field in EM configs. `BOARD_CONFIG_NAME`,
 `PRODUCT_CONFIG_NAME`, and `BOARD_PART_NUMBER` are valid probe fields, and if a
 scanned FRU matches these fields, the object will be created from this config.

 An example definition:

 ```
 ...
   "ProbeV2": {
       "IpmiFru": {
           "BOARD_PRODUCT_NAME": "foo"
       }
   },
 ...
 ```

 The `ProbeV2` field can also be set to `TRUE` to always be populated regardless
 of matching a scanned FRU, or it can be set to `FALSE` to be ignored.

 An example definition:

 ```
 ...
 "ProbeV2": "TRUE",
 ...
 ```

 #### Logical AND and OR Syntax

 Logical AND and OR syntax is supported for the IpmiFru field if given an array
 of JSON objects instead of a single JSON.

 The logical AND operation is applied for all fields within a single IpmiFru
 JSON. For the matcher to evaluate as True, every field must be a match.

 An example definition:

 ```
 // In this example, the scanned FRU must have both the BOARD_PRODUCT_NAME = foo
 // and the BOARD_PART_NUMBER = 1234567890 to successfully probe to True
 ...
   "ProbeV2": {
     "IpmiFru": [
       {
         "BOARD_PRODUCT_NAME": "foo",
         "BOARD_PART_NUMBER": "1234567890"
       }
     ]
   }
 ...
 ```

 The logical OR operation is applied between matcher objects within the array of
 IpmiFru JSONs. If any one of the matchers evaluates to True, considering the
 logical AND syntax above, the Probe will be evaluated as True.

 An example definition:

 ```
 // In this example, the scanned FRU must have either the BOARD_PRODUCT_NAME = foo
 // or the BOARD_PART_NUMBER = 1234567890 to successfully probe to True. If either
 // field matches, the probe will be successful regardless of the value of the other field
 ...
   "ProbeV2": {
     "IpmiFru": [
       {
         "BOARD_PRODUCT_NAME": "foo"
       },
       {
         "BOARD_PART_NUMBER": "1234567890"
       }
     ]
   }
 ...
 ```

 Note: `FOUND` behaviors are not yet supported by tlBMC.

 ### ResourceType

 `ResourceType` has parity with the `Type` field in existing EM configs.

 Supported resource types are defined in `tlbmc/resource/resource.proto`.

 An example definition:

 ```
 ...
 "ResourceType": "RESOURCE_TYPE_BOARD",
 ...
 ```

 #### ChassisType

 For configs of `RESOURCE_TYPE_BOARD` an `ChassisType` is needed as a additional
 field. This field has parity with the EM config field
 `xyz.openbmc_project.Inventory.Item.Chassis.ChassisType`. This field will
 default to type `RackMount`.

 Supported chassis types are defined in `tlbmc/resource/resource.proto`.

 An example definition:

 ```
 ...
 "ChassisType": "CHASSIS_TYPE_COMPONENT",
 ...
 ```

 ### Downstream/Upstream Ports

 Physical ports are modeled as downstream/upstream ports between Chassis. These
 are fields in the `Exposes` array of a config and may correspond to existing
 ports. Similar to existing EM configs, a port on an upstream chassis to a
 downstream chassis has a `Label` field, used to populate the devpath. These
 ports will have the `Type` of `PortDownstream`. On the downstream chassis, there
 will be a corresponding port with the same name, but the `Type` will be
 `UpstreamConnection`.

 Tip: Only one chassis (the root chassis) will have no `UpstreamConnection` or
 `CableUpstreamConnection`. This is enforced by tlBMC and the store will fail to
 create if this condition is not true.

 Note: In contrast to Entity Manager, "Upstream" and "Downstream" in tlBMC refers
 to the relationship of a component that is upstream/downstream of the component
 where the port exists. For instance, a root chassis has no `UpstreamConnection`,
 but can have many `PortDownstream` since all other components must be downstream
 in relation to the root chassis. In traditional Entity Manager,
 upstream/downstream refers to the role of the component directly.

 An example of a `PortDownstream` port:

 ```
 "Exposes": [
   ...
     {
         "Label": "bar",
         "Name": "Foo $bus Port",
         "Type": "PortDownstream",
         "User": "tlbmc"
     },
   ...
 ],
 ```

 and the corresponding `UpstreamConnection` port:

 ```
 "Exposes": [
   ...
     {
         "Name": "Foo $bus Port",
         "Type": "UpstreamConnection",
         "User": "tlbmc"
     },
   ...
 ],
 ```

 Note: The name field must match exactly between `PortDownstream` and
 `UpstreamConnection` ports. This is how topology is created and `contains` and
 `contained_by` associations are populated.

 ### Substitution

 Any fields in the `Exposes` field, including all Port configurations will
 support `$bus` and `$index` substitution. This includes substitution with
 mathematical expressions. Mathematical expressions are evaluated strictly left
 to right in substitution and will stop at the end of the string or first
 non-numeric/operator character encountered. An ill-formed mathematical
 expression will cause parsing error.

 Examples of substitution:

 ```
 Assuming bus = 3,

 "Exposes": [
   {
     "Label": "IO0",
     "Name": "Port $bus",
     "Type": "PortDownstream",
     "REASON": "Valid, simple bus substitution. Evaluates to `Port 3`."
   },
   {
     "Label": "IO0",
     "Name": "Port $bus - 5 * 3 + 54",
     "Type": "PortDownstream",
     "REASON": "Valid, bus substitution with mathematical expression. Evaluates to `Port 48`."
   },
   {
     "Label": "IO0",
     "Name": "Port $bus - 5 * 3 + 54 something",
     "Type": "PortDownstream",
     "REASON": "Valid, simple bus substitution with mathematical expression and remainder. Evaluates to `Port 48 something`."
   },
   {
     "Label": "IO0",
     "Name": "Port $bus / 0",
     "Type": "PortDownstream",
     "REASON": "Invalid, division by zero"
   },
   {
     "Label": "IO0",
     "Name": "Port $bus - something",
     "Type": "PortDownstream",
     "REASON": "Invalid, hanging operator"
   }
 ]

 ```

 ### PartLocationType

 `PartLocationType` has parity with the `xyz.openbmc_project.Inventory.Connector`
 field in existing EM configs.

 PartLocationTypes are defined in
 [topology_config.proto](https://gbmc.googlesource.com/gbmcweb/+/refs/heads/master/tlbmc/topology_config.proto).

 Note: All subfrus MUST have a PartLocationType of PART_LOCATION_TYPE_EMBEDDED.
 tlBMC will error if a subfru is misconfigured to not use the embedded type.

 An example definition:

 ```
 ...
     "PartLocationType": "PART_LOCATION_TYPE_SLOT",
 ...
 ```

 ### Processors

 `Processor` is a field unique to tlBMC, since these can no longer be detected
 through dbus, they must be defined in the static configuration. Processors are
 defined in the `Exposes` field of a config, with a `Name` and `"Type":
 "Processor"`.

 An example definition:

 ```
 "Exposes": [
   ...
     {
         "Name": "cpu0",
         "Type": "Processor",
         "User": "tlbmc"
     },
   ...
 ],
 ```

 ### Storage

 `Storage` has parity with the `xyz.openbmc_project.Inventory.Item.Storage`
 field. This field is a JSON with a single `Id` field. The storage field is used
 to create the link to the associated Storage object in the redfish query
 response, the value of `Id` should be the `Id` of the associated Storage object.

 An example definition:

 ```
 ...
   "Storage": {
       "Id": "foo_storage_$index"
   },
 ...
 ```

 ### Asset

 `Asset` has parity with the `xyz.openbmc_project.Inventory.Decorator.Asset`
 field in existing EM configs. This field allows users to override the
 Manufacturer, Model, PartNumber, or SerialNumber in the redfish response. Valid
 substitutions are defined in the same way as in the OpenBMC definition, for
 example: `$PRODUCT_PART_NUMBER` or `$BOARD_MANUFACTURER` will substitute the
 respective field from the scanned FRU object. Fields can also be overridden with
 any string that is not prefixed with `$`.

 Tip: if a substitution is attempted (prefixed with `$`) but fails, tlBMC will
 error.

 An example definition:

 ```
 ...
   "Asset": {
       "Manufacturer": "$BOARD_MANUFACTURER",
       "Model": "foo",
       "PartNumber": "$BOARD_PART_NUMBER",
       "SerialNumber": "$BOARD_SERIAL_NUMBER",
       "User": "tlbmc"
   },
 ...
 ```

 ### Ad-Hoc Frus

 Certain FRUs require special handling as they may not be scannable when bmcweb
 comes up. For this purpose, we have created something called an "Ad-Hoc Fru
 Scanner". This will allow you to configure exactly how you want to scan a FRU.

 An example is below:

 ```
         "AdHocFruConfig": {
             "name": "AdHocFru",
             "i2c_common_config": {
                 "bus": "4",
                 "address": "83"
             },
             "delay_between_reads": "0.001s",
             "periodic_scan_config": [
                 {
                     "scan_interval": "10s",
                     "scan_count": 6
                 },
                 {
                     "scan_interval": "60s",
                     "scan_count": 9
                 },
                 {
                     "scan_interval": "600s",
                     "scan_count": 5
                 }
             ]
         }
 ```

 The proto definition is found
 [here](https://gbmc.googlesource.com/gbmcweb/+/refs/heads/master/tlbmc/ad_hoc_fru_config.proto).

 > NOTE: This must go inside the ProbeV2 Json Object.

 ## Subfrus

 Some objects are not uniquely FRU-detectable like a regular chassis and are
 logically separate from a given chassis, defined in their own EM configuration.
 These objects are considered Subfrus.

 ### Assemblies

 Assemblies are subfrus that may have their own devpath, Manufacturer, Serial
 Number, Model, etc. Assemblies represent a component that is logically separate
 but are not I2C scannable and do not have an eeprom.

 An assembly is always defined with `"ResourceType": "RESOURCE_TYPE_ASSEMBLY"`,
 this has parity with the `"Type": "Component"` field in existing EM configs.

 Assemblies will have PartLocationType of either `PART_LOCATION_TYPE_EMBEDDED` or
 `PART_LOCATION_TYPE_SLOT`. This should follow what is in the existing EM config.

 *   `PART_LOCATION_TYPE_EMBEDDED`: This represents an assembly that is
     physically attached to the parent board and cannot be replaced on its own.
     An example of this configuration is provided below:

     ```
     {
       "Exposes": [
         {
           "Name": "Foo Sensor Controller 0 Port",
           "Type": "UpstreamConnection",
           "User": "tlbmc"
         },
         {
           "Name": "foo_0_variant_a_sensors",
           "Address": "0x68",
           "Bus": "64",
           "Labels": [
             "vin1",
             "iin1",
             "pin1"
           ],
           "vin1_Name": "foo_0_a_vin",
           "iin1_Name": "foo_0_a_iin",
           "pin1_Name": "foo_0_a_pin",
           "Type": "XDPE1A2G5B",
           "TlbmcOwned": true,
           "SkipDbusRead": true
         }
       ],
       "Name": "Foo Sensor Controller 0 Var A",
       "ProbeV2": {
         "IpmiFru": {
           "PRODUCT_PRODUCT_NAME": "^Foo_Parent_Variant_A$"
         }
       },
       "ResourceType": "RESOURCE_TYPE_ASSEMBLY",
       "PartLocationType": "PART_LOCATION_TYPE_EMBEDDED",
       "Type": "Component",
       "xyz.openbmc_project.Inventory.Connector.Embedded": {},
       "xyz.openbmc_project.Inventory.Decorator.Asset": {
         "Manufacturer": "Foo_Manufacturer",
         "Model": "Foo_Controller_Model"
       }
     },
     ```

 *   `PART_LOCATION_TYPE_SLOT`: This represents a component that is attached to
     the parent chassis through a slot and can be individually replaced, although
     it is not FRU detectable.
     An example of this configuration is provided below:

     ```
     {
       "Exposes": [
         {
           "Name": "Bar Port",
           "Type": "UpstreamConnection",
           "User": "tlbmc"
         },
         {
           "Address": "0x42",
           "Bus": "21",
           "Name": "bar_sensor1",
           "Name1": "bar_sensor2",
           "Name2": "bar_sensor3",
           "Labels": [
             "sensor1",
             "sensor2",
             "sensor3"
           ],
           "Type": "TMP75",
           "TlbmcOwned": true,
           "SkipDbusRead": true
         }
       ],
       "Name": "Bar Assembly",
       "ProbeV2": "TRUE",
       "ResourceType": "RESOURCE_TYPE_ASSEMBLY",
       "PartLocationType": "PART_LOCATION_TYPE_SLOT",
       "Type": "Component",
       "xyz.openbmc_project.Inventory.Connector.Slot": {},
       "Asset": {
         "Model": "Bar_Assembly_Model"
       }
     }

     ```

 Assemblies may have their own sensors defined. These will be propagated to the
 parent chassis object since Assemblies cannot directly own sensors. This allows
 for sensors that will only be present on certain board variants to be defined in
 a separate config without having to duplicate the whole parent board
 configuration.

 Note: tlBMC does not currently own the Assembly redfish path. The sensor
 propagation described above is the only feature supported by tlBMC. Querying
 assemblies at `/redfish/v1/Chassis/{ChassisId}/Assembly` will be routed through
 non-tlBMC Bmcweb.

 An example definition:

 ```
 {
     "Exposes": [
       {
         "Name": "Assembly A Port",
         "Type": "UpstreamConnection",
         "User": "tlbmc"
       },
       {
         "Name": "variant_a_psu_sensor",
         "Address": "0x68",
         "Bus": "64",
         "Labels": [
           "vin1",
           "pin1",
           "vout1",
           "iout1"
         ],
         "vin1_Name": "foo_a_vin",
         "pin1_Name": "foo_a_pin",
         "vout1_Name": "foo_a_vout",
         "iout1_Name": "foo_a_iout",
         "Type": "ADM1266",
         "TlbmcOwned": true,
         "SkipDbusRead": true
       }
     ],
     "Name": "Foo Assembly A",
     "ProbeV2": {
       "IpmiFru": {
         "PRODUCT_PRODUCT_NAME": "^FooVariant$"
       }
     },
     "ResourceType": "RESOURCE_TYPE_ASSEMBLY",
     "PartLocationType": "PART_LOCATION_TYPE_EMBEDDED",
     "Type": "Component",
     "xyz.openbmc_project.Inventory.Connector.Embedded": {},
     ...
   },
 ```

 The sensors defined here in the `variant_a_psu_sensor` config would be
 propagated to the parent board, `Foo` which would be expected to have a
 `PortDownstream` connection with the name `Assembly A Port`. Note again that
 tlBMC does not own Assemblies, but due to `"Type": "Component",` being in the
 config, `Foo Assembly A` can be queried under
 `/redfish/v1/Chassis/Foo/Assembly`.

 ## Cables

 ### Cable Connections

 Cables are defined similar to Chassis and are associated through same
 `PortDownstream` and `UpstreamConnection` type ports in their `Exposes` field.
 Cable configs should have their `ProbeV2` field set to either `TRUE` (if they
 cannot be detected through I2C) or same `IpmiFru` config like those in chassis,
 with their `ResourceType` set to `RESOURCE_TYPE_CABLE`. The associated upstream
 or downstream Chassis must have a port with the opposite connection type and the
 same `Name` to form a connection. The field `Label` must be defined in the
 exposed port. In the case that some cables are not used to generate devpath, the
 `Label` field should be set as `DontSetDevpath`. tlBMC will generate
 corresponding connection without assigning devpath for such topology.

 An example Cable config:

 ```
 {
     "Exposes": [
         {
             "Name": "Foo Cable Downstream",
             "Type": "UpstreamConnection",
             "User": "tlbmc"
         },
         {
             "Name": "Foo Cable Upstream",
             "Label": "FooCable",
             "Type": "PortDownstream",
             "User": "tlbmc"
         }
     ],
     "Name": "FooCable",
     "Probe": "xyz.openbmc_project.Network.EthernetInterface({'InterfaceName': '^foo$', 'LinkUp': true})",
     "ProbeV2": "TRUE",
     "ResourceType": "RESOURCE_TYPE_CABLE",
     "Type": "Cable"
 }
 ```

 The upstream chassis exposes a PortDownstream:

 ```
 "Exposes": {
   ...
     {
         "Name": "Foo Cable Downstream",
         "Label": "FooCable",
         "Type": "PortDownstream",
         "User": "tlbmc"
     },
   ...
 },
 ```

 and the downstream chassis exposes a UpstreamConnection:

 ```
 "Exposes": {
   ...
     {
         "Name": "Foo Cable Upstream",
         "Type": "UpstreamConnection",
         "User": "tlbmc"
     },
   ...
 },
 ```
	# Onboarding NPIs to Fru Collector Module

	go/tlbmc-onboarding-npis

	<!--*
	# Document freshness: For more information, see go/fresh-source.
	freshness: { owner: 'tlbmc-dev' reviewed: '2025-10-13' }
	*-->

	This document outlines the additions necessary to Entity-Manager (EM) JSON
	configuration files to enable fru collector module on an NPI.
	[Entity-Manager](https://github.com/openbmc/entity-manager) provides mappings
	from hardware components to software components within a system, these mappings
	are managed through EM configuration files as described here.

	Note: tlBMC requires only additions to existing EM config files, no deletions or
	modifications of existing properties should occur. This allows tlBMC to be
	backward compatible with existing bmcweb without conflicting behavior. Original
	design doc can be viewed at go/tlbmc-data-completeness

	Tip: Existing daemons, e.g. PSU sensors, will still coexist if not disabled
	explicitly. Whether these should be configured depends on the use case. If the
	sensor is only used in telemetry reporting not control, e.g. PID, tlBMC can
	fully replace existing daemons. In this case, see the section **SkipDbusRead
	Property** which describes how to disable sensor polling over dbus to
	significantly improve CPU utilization.

	## Prerequisites

	The tlBMC FRU Collector Module must be enabled for your platform in
	`tlbmc_config_bundle.textproto`. If it is not enabled, tlBMC will not collect
	FRU data regardless of EM configuration.
	See `tlbmc_config_bundle.textproto` in tlbmc source.

	[TOC]

	## Chassis

	### ProbeV2

	The addition of the ProbeV2 field makes the config detectable by tlBMC. The
	value of the `IpmiFru` JSON within the ProbeV2 field corresponds with the
	existing `Probe` field in EM configs. `BOARD_CONFIG_NAME`,
	`PRODUCT_CONFIG_NAME`, and `BOARD_PART_NUMBER` are valid probe fields, and if a
	scanned FRU matches these fields, the object will be created from this config.

	An example definition:

	```
	...
	"ProbeV2": {
	"IpmiFru": {
	"BOARD_PRODUCT_NAME": "foo"
	}
	},
	...
	```

	The `ProbeV2` field can also be set to `TRUE` to always be populated regardless
	of matching a scanned FRU, or it can be set to `FALSE` to be ignored.

	An example definition:

	```
	...
	"ProbeV2": "TRUE",
	...
	```

	#### Logical AND and OR Syntax

	Logical AND and OR syntax is supported for the IpmiFru field if given an array
	of JSON objects instead of a single JSON.

	The logical AND operation is applied for all fields within a single IpmiFru
	JSON. For the matcher to evaluate as True, every field must be a match.

	An example definition:

	```
	// In this example, the scanned FRU must have both the BOARD_PRODUCT_NAME = foo
	// and the BOARD_PART_NUMBER = 1234567890 to successfully probe to True
	...
	"ProbeV2": {
	"IpmiFru": [
	{
	"BOARD_PRODUCT_NAME": "foo",
	"BOARD_PART_NUMBER": "1234567890"
	}
	]
	}
	...
	```

	The logical OR operation is applied between matcher objects within the array of
	IpmiFru JSONs. If any one of the matchers evaluates to True, considering the
	logical AND syntax above, the Probe will be evaluated as True.

	An example definition:

	```
	// In this example, the scanned FRU must have either the BOARD_PRODUCT_NAME = foo
	// or the BOARD_PART_NUMBER = 1234567890 to successfully probe to True. If either
	// field matches, the probe will be successful regardless of the value of the other field
	...
	"ProbeV2": {
	"IpmiFru": [
	{
	"BOARD_PRODUCT_NAME": "foo"
	},
	{
	"BOARD_PART_NUMBER": "1234567890"
	}
	]
	}
	...
	```

	Note: `FOUND` behaviors are not yet supported by tlBMC.

	### ResourceType

	`ResourceType` has parity with the `Type` field in existing EM configs.

	Supported resource types are defined in `tlbmc/resource/resource.proto`.

	An example definition:

	```
	...
	"ResourceType": "RESOURCE_TYPE_BOARD",
	...
	```

	#### ChassisType

	For configs of `RESOURCE_TYPE_BOARD` an `ChassisType` is needed as a additional
	field. This field has parity with the EM config field
	`xyz.openbmc_project.Inventory.Item.Chassis.ChassisType`. This field will
	default to type `RackMount`.

	Supported chassis types are defined in `tlbmc/resource/resource.proto`.

	An example definition:

	```
	...
	"ChassisType": "CHASSIS_TYPE_COMPONENT",
	...
	```

	### Downstream/Upstream Ports

	Physical ports are modeled as downstream/upstream ports between Chassis. These
	are fields in the `Exposes` array of a config and may correspond to existing
	ports. Similar to existing EM configs, a port on an upstream chassis to a
	downstream chassis has a `Label` field, used to populate the devpath. These
	ports will have the `Type` of `PortDownstream`. On the downstream chassis, there
	will be a corresponding port with the same name, but the `Type` will be
	`UpstreamConnection`.

	Tip: Only one chassis (the root chassis) will have no `UpstreamConnection` or
	`CableUpstreamConnection`. This is enforced by tlBMC and the store will fail to
	create if this condition is not true.

	Note: In contrast to Entity Manager, "Upstream" and "Downstream" in tlBMC refers
	to the relationship of a component that is upstream/downstream of the component
	where the port exists. For instance, a root chassis has no `UpstreamConnection`,
	but can have many `PortDownstream` since all other components must be downstream
	in relation to the root chassis. In traditional Entity Manager,
	upstream/downstream refers to the role of the component directly.

	An example of a `PortDownstream` port:

	```
	"Exposes": [
	...
	{
	"Label": "bar",
	"Name": "Foo $bus Port",
	"Type": "PortDownstream",
	"User": "tlbmc"
	},
	...
	],
	```

	and the corresponding `UpstreamConnection` port:

	```
	"Exposes": [
	...
	{
	"Name": "Foo $bus Port",
	"Type": "UpstreamConnection",
	"User": "tlbmc"
	},
	...
	],
	```

	Note: The name field must match exactly between `PortDownstream` and
	`UpstreamConnection` ports. This is how topology is created and `contains` and
	`contained_by` associations are populated.

	### Substitution

	Any fields in the `Exposes` field, including all Port configurations will
	support `$bus` and `$index` substitution. This includes substitution with
	mathematical expressions. Mathematical expressions are evaluated strictly left
	to right in substitution and will stop at the end of the string or first
	non-numeric/operator character encountered. An ill-formed mathematical
	expression will cause parsing error.

	Examples of substitution:

	```
	Assuming bus = 3,

	"Exposes": [
	{
	"Label": "IO0",
	"Name": "Port $bus",
	"Type": "PortDownstream",
	"REASON": "Valid, simple bus substitution. Evaluates to `Port 3`."
	},
	{
	"Label": "IO0",
	"Name": "Port $bus - 5 * 3 + 54",
	"Type": "PortDownstream",
	"REASON": "Valid, bus substitution with mathematical expression. Evaluates to `Port 48`."
	},
	{
	"Label": "IO0",
	"Name": "Port $bus - 5 * 3 + 54 something",
	"Type": "PortDownstream",
	"REASON": "Valid, simple bus substitution with mathematical expression and remainder. Evaluates to `Port 48 something`."
	},
	{
	"Label": "IO0",
	"Name": "Port $bus / 0",
	"Type": "PortDownstream",
	"REASON": "Invalid, division by zero"
	},
	{
	"Label": "IO0",
	"Name": "Port $bus - something",
	"Type": "PortDownstream",
	"REASON": "Invalid, hanging operator"
	}
	]

	```

	### PartLocationType

	`PartLocationType` has parity with the `xyz.openbmc_project.Inventory.Connector`
	field in existing EM configs.

	PartLocationTypes are defined in
	[topology_config.proto](https://gbmc.googlesource.com/gbmcweb/+/refs/heads/master/tlbmc/topology_config.proto).

	Note: All subfrus MUST have a PartLocationType of PART_LOCATION_TYPE_EMBEDDED.
	tlBMC will error if a subfru is misconfigured to not use the embedded type.

	An example definition:

	```
	...
	"PartLocationType": "PART_LOCATION_TYPE_SLOT",
	...
	```

	### Processors

	`Processor` is a field unique to tlBMC, since these can no longer be detected
	through dbus, they must be defined in the static configuration. Processors are
	defined in the `Exposes` field of a config, with a `Name` and `"Type":
	"Processor"`.

	An example definition:

	```
	"Exposes": [
	...
	{
	"Name": "cpu0",
	"Type": "Processor",
	"User": "tlbmc"
	},
	...
	],
	```

	### Storage

	`Storage` has parity with the `xyz.openbmc_project.Inventory.Item.Storage`
	field. This field is a JSON with a single `Id` field. The storage field is used
	to create the link to the associated Storage object in the redfish query
	response, the value of `Id` should be the `Id` of the associated Storage object.

	An example definition:

	```
	...
	"Storage": {
	"Id": "foo_storage_$index"
	},
	...
	```

	### Asset

	`Asset` has parity with the `xyz.openbmc_project.Inventory.Decorator.Asset`
	field in existing EM configs. This field allows users to override the
	Manufacturer, Model, PartNumber, or SerialNumber in the redfish response. Valid
	substitutions are defined in the same way as in the OpenBMC definition, for
	example: `$PRODUCT_PART_NUMBER` or `$BOARD_MANUFACTURER` will substitute the
	respective field from the scanned FRU object. Fields can also be overridden with
	any string that is not prefixed with `$`.

	Tip: if a substitution is attempted (prefixed with `$`) but fails, tlBMC will
	error.

	An example definition:

	```
	...
	"Asset": {
	"Manufacturer": "$BOARD_MANUFACTURER",
	"Model": "foo",
	"PartNumber": "$BOARD_PART_NUMBER",
	"SerialNumber": "$BOARD_SERIAL_NUMBER",
	"User": "tlbmc"
	},
	...
	```

	### Ad-Hoc Frus

	Certain FRUs require special handling as they may not be scannable when bmcweb
	comes up. For this purpose, we have created something called an "Ad-Hoc Fru
	Scanner". This will allow you to configure exactly how you want to scan a FRU.

	An example is below:

	```
	"AdHocFruConfig": {
	"name": "AdHocFru",
	"i2c_common_config": {
	"bus": "4",
	"address": "83"
	},
	"delay_between_reads": "0.001s",
	"periodic_scan_config": [
	{
	"scan_interval": "10s",
	"scan_count": 6
	},
	{
	"scan_interval": "60s",
	"scan_count": 9
	},
	{
	"scan_interval": "600s",
	"scan_count": 5
	}
	]
	}
	```

	The proto definition is found
	[here](https://gbmc.googlesource.com/gbmcweb/+/refs/heads/master/tlbmc/ad_hoc_fru_config.proto).

	> NOTE: This must go inside the ProbeV2 Json Object.

	## Subfrus

	Some objects are not uniquely FRU-detectable like a regular chassis and are
	logically separate from a given chassis, defined in their own EM configuration.
	These objects are considered Subfrus.

	### Assemblies

	Assemblies are subfrus that may have their own devpath, Manufacturer, Serial
	Number, Model, etc. Assemblies represent a component that is logically separate
	but are not I2C scannable and do not have an eeprom.

	An assembly is always defined with `"ResourceType": "RESOURCE_TYPE_ASSEMBLY"`,
	this has parity with the `"Type": "Component"` field in existing EM configs.

	Assemblies will have PartLocationType of either `PART_LOCATION_TYPE_EMBEDDED` or
	`PART_LOCATION_TYPE_SLOT`. This should follow what is in the existing EM config.

	* `PART_LOCATION_TYPE_EMBEDDED`: This represents an assembly that is
	physically attached to the parent board and cannot be replaced on its own.
	An example of this configuration is provided below:

	```
	{
	"Exposes": [
	{
	"Name": "Foo Sensor Controller 0 Port",
	"Type": "UpstreamConnection",
	"User": "tlbmc"
	},
	{
	"Name": "foo_0_variant_a_sensors",
	"Address": "0x68",
	"Bus": "64",
	"Labels": [
	"vin1",
	"iin1",
	"pin1"
	],
	"vin1_Name": "foo_0_a_vin",
	"iin1_Name": "foo_0_a_iin",
	"pin1_Name": "foo_0_a_pin",
	"Type": "XDPE1A2G5B",
	"TlbmcOwned": true,
	"SkipDbusRead": true
	}
	],
	"Name": "Foo Sensor Controller 0 Var A",
	"ProbeV2": {
	"IpmiFru": {
	"PRODUCT_PRODUCT_NAME": "^Foo_Parent_Variant_A$"
	}
	},
	"ResourceType": "RESOURCE_TYPE_ASSEMBLY",
	"PartLocationType": "PART_LOCATION_TYPE_EMBEDDED",
	"Type": "Component",
	"xyz.openbmc_project.Inventory.Connector.Embedded": {},
	"xyz.openbmc_project.Inventory.Decorator.Asset": {
	"Manufacturer": "Foo_Manufacturer",
	"Model": "Foo_Controller_Model"
	}
	},
	```

	* `PART_LOCATION_TYPE_SLOT`: This represents a component that is attached to
	the parent chassis through a slot and can be individually replaced, although
	it is not FRU detectable.
	An example of this configuration is provided below:

	```
	{
	"Exposes": [
	{
	"Name": "Bar Port",
	"Type": "UpstreamConnection",
	"User": "tlbmc"
	},
	{
	"Address": "0x42",
	"Bus": "21",
	"Name": "bar_sensor1",
	"Name1": "bar_sensor2",
	"Name2": "bar_sensor3",
	"Labels": [
	"sensor1",
	"sensor2",
	"sensor3"
	],
	"Type": "TMP75",
	"TlbmcOwned": true,
	"SkipDbusRead": true
	}
	],
	"Name": "Bar Assembly",
	"ProbeV2": "TRUE",
	"ResourceType": "RESOURCE_TYPE_ASSEMBLY",
	"PartLocationType": "PART_LOCATION_TYPE_SLOT",
	"Type": "Component",
	"xyz.openbmc_project.Inventory.Connector.Slot": {},
	"Asset": {
	"Model": "Bar_Assembly_Model"
	}
	}

	```

	Assemblies may have their own sensors defined. These will be propagated to the
	parent chassis object since Assemblies cannot directly own sensors. This allows
	for sensors that will only be present on certain board variants to be defined in
	a separate config without having to duplicate the whole parent board
	configuration.

	Note: tlBMC does not currently own the Assembly redfish path. The sensor
	propagation described above is the only feature supported by tlBMC. Querying
	assemblies at `/redfish/v1/Chassis/{ChassisId}/Assembly` will be routed through
	non-tlBMC Bmcweb.

	An example definition:

	```
	{
	"Exposes": [
	{
	"Name": "Assembly A Port",
	"Type": "UpstreamConnection",
	"User": "tlbmc"
	},
	{
	"Name": "variant_a_psu_sensor",
	"Address": "0x68",
	"Bus": "64",
	"Labels": [
	"vin1",
	"pin1",
	"vout1",
	"iout1"
	],
	"vin1_Name": "foo_a_vin",
	"pin1_Name": "foo_a_pin",
	"vout1_Name": "foo_a_vout",
	"iout1_Name": "foo_a_iout",
	"Type": "ADM1266",
	"TlbmcOwned": true,
	"SkipDbusRead": true
	}
	],
	"Name": "Foo Assembly A",
	"ProbeV2": {
	"IpmiFru": {
	"PRODUCT_PRODUCT_NAME": "^FooVariant$"
	}
	},
	"ResourceType": "RESOURCE_TYPE_ASSEMBLY",
	"PartLocationType": "PART_LOCATION_TYPE_EMBEDDED",
	"Type": "Component",
	"xyz.openbmc_project.Inventory.Connector.Embedded": {},
	...
	},
	```

	The sensors defined here in the `variant_a_psu_sensor` config would be
	propagated to the parent board, `Foo` which would be expected to have a
	`PortDownstream` connection with the name `Assembly A Port`. Note again that
	tlBMC does not own Assemblies, but due to `"Type": "Component",` being in the
	config, `Foo Assembly A` can be queried under
	`/redfish/v1/Chassis/Foo/Assembly`.

	## Cables

	### Cable Connections

	Cables are defined similar to Chassis and are associated through same
	`PortDownstream` and `UpstreamConnection` type ports in their `Exposes` field.
	Cable configs should have their `ProbeV2` field set to either `TRUE` (if they
	cannot be detected through I2C) or same `IpmiFru` config like those in chassis,
	with their `ResourceType` set to `RESOURCE_TYPE_CABLE`. The associated upstream
	or downstream Chassis must have a port with the opposite connection type and the
	same `Name` to form a connection. The field `Label` must be defined in the
	exposed port. In the case that some cables are not used to generate devpath, the
	`Label` field should be set as `DontSetDevpath`. tlBMC will generate
	corresponding connection without assigning devpath for such topology.

	An example Cable config:

	```
	{
	"Exposes": [
	{
	"Name": "Foo Cable Downstream",
	"Type": "UpstreamConnection",
	"User": "tlbmc"
	},
	{
	"Name": "Foo Cable Upstream",
	"Label": "FooCable",
	"Type": "PortDownstream",
	"User": "tlbmc"
	}
	],
	"Name": "FooCable",
	"Probe": "xyz.openbmc_project.Network.EthernetInterface({'InterfaceName': '^foo$', 'LinkUp': true})",
	"ProbeV2": "TRUE",
	"ResourceType": "RESOURCE_TYPE_CABLE",
	"Type": "Cable"
	}
	```

	The upstream chassis exposes a PortDownstream:

	```
	"Exposes": {
	...
	{
	"Name": "Foo Cable Downstream",
	"Label": "FooCable",
	"Type": "PortDownstream",
	"User": "tlbmc"
	},
	...
	},
	```

	and the downstream chassis exposes a UpstreamConnection:

	```
	"Exposes": {
	...
	{
	"Name": "Foo Cable Upstream",
	"Type": "UpstreamConnection",
	"User": "tlbmc"
	},
	...
	},
	```