xref: /openbmc/entity-manager/docs/entity_manager_dbus_api.md (revision 3ce9143fb05f3f9e96d62797d9cd22a4b4441c30) 
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```
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 [upstream types](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Inventory/Item)
36
37* BMC
38* Board
39* Chassis
40* CPU
41* ...
42
43These types closely align with Redfish types.
44
45Entity objects describe pieces of physical hardware.
46
47##### Properties:
48
49unsigned int: num_children: Number of configurations under this entity.
50
51std::string name: name of the inventory item
52
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```
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```
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```
109exposes :
110[
111    {
112        "name" : "front panel temp",
113        "property": {"key: "value"}
114    }
115]
116```
117
118Not Legal:
119
120```
121exposes :
122[
123    {
124        "name" : "front panel temp",
125        "property": {
126            "key": {
127                "key2": "value"
128            }
129        }
130    }
131]
132
133```
134