xref: /openbmc/entity-manager/docs/entity_manager_dbus_api.md (revision ec1137d54552e346ee3d9d7f7c647316dbb5794f) 
1# Entity Manager DBus API
2
3The Entity Manager is in charge of inventory management by scanning JSON files
4and representing the data on DBus in a meaningful way. For more information on
5the internal structure of the Entity Manager, please refer to the README of the
6Entity Manager. This file documents a consumers usage of the entity manager, and
7is not a description of the internal workings.
8
9## DBus Object
10
11### Object Paths
12
13#### Entities: `/xyz/openbmc_project/Inventory/Item/{Entity Type}/{Entity Name}`
14
15Entities are top level json objects that describe a piece of hardware. They are
16groups of configurations with few properties of their own, they are a container
17type for most pratical purposes.
18
19#### Devices: `/xyz/openbmc_project/Inventory/Item/{Entity Type}/{Entity Name}/{Configuration}`
20
21Configurations are components that are exposed when an entity is added to the
22"global" system configuration. An example would be a TMP75 sensor that is
23exposed when the front panel is detected.
24
25**Example**:
26
27```text
28/xyz/openbmc_project/Inventory/Item/Board/Intel_Front_Panel/Front_Panel_Temp
29```
30
31### Interfaces
32
33#### `xyz.openbmc_project.{InventoryType}`
34
35See
36[upstream types](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Inventory/Item)
37
38- BMC
39- Board
40- Chassis
41- CPU
42- ...
43
44These types closely align with Redfish types.
45
46Entity objects describe pieces of physical hardware.
47
48##### Properties
49
50`unsigned int num_children`: Number of configurations under this entity.
51
52`std::string name`: name of the inventory item
53
54#### `xyz.openbmc_project.Configuration`
55
56Configuration objects describe components owned by the Entity.
57
58##### Properties
59
60Properties will contain all non-objects (simple types) exposed by the JSON.
61
62**Example**:
63
64```text
65path: /xyz/openbmc_project/Inventory/Item/Board/Intel_Front_Panel/Front_Panel_Temp
66Interface: xyz.openbmc_project.Configuration
67    string name = "front panel temp"
68    string address = "0x4D"
69    string "bus" = "1"
70```
71
72#### `xyz.openbmc_project.Device.{Object}.{index}`
73
74{Object}s are members of the parent device that were originally described as
75dictionaries. This allows for creating more complex types, while still being
76able to get a picture of the entire system when doing a get managed objects
77method call. Array objects will be indexed zero based.
78
79##### Properties
80
81All members of the dictonary.
82
83**Example**:
84
85```text
86path: /xyz/openbmc_project/Inventory/Item/Board/Intel_Front_Panel/Front_Panel_Temp
87Interface: xyz.openbmc_project.Device.threshold.0
88    string direction = "greater than"
89    int value = 55
90```
91
92## JSON Requirements
93
94### JSON syntax requirements
95
96Based on the above DBus object, there is an implicit requirement that device
97objects may not have more than one level deep of dictionary or list of
98dictionary. It is possible to extend in the future to allow nearly infinite
99levels deep of dictonary with extending the
100**xyz.openbmc_project.Device.{Object}** to allow
101**xyz.openbmc_project.Device.{Object}.{SubObject}.{SubObject}** but that
102complexity will be avoided until proven needed.
103
104**Example**:
105
106Legal:
107
108```text
109exposes :
110[
111    {
112        "name" : "front panel temp",
113        "property": {"key: "value"}
114    }
115]
116```
117
118Not Legal:
119
120```text
121exposes :
122[
123    {
124        "name" : "front panel temp",
125        "property": {
126            "key": {
127                "key2": "value"
128            }
129        }
130    }
131]
132```
133