OpenBMC DBUS API

This document aims to specify the OpenBMC DBUS API.

The Phosphor distribution provides sample applications that implement off all the interfaces and objects listed below. Alternative or more feature complete applications are possible by implementing parts of this DBUS API.

OpenBMC typically adheres to DBUS best practices and usage models; however, one deviation is that OpenBMC places no requirements on well known service names. This allows developers to structure their object implementations in whatever processes they choose. In the standard DBUS programming model, applications connect to a service with a well known name. The well known name is associated with a fixed schema. In OpenBMC, without any standardization of well known names, applications lose the knowledge of what applications provide which objects. To address this, the Phosphor distribution provides the objectmapper service. See the org.openbmc.objectmapper.ObjectMapper interface below for more information.

The OpenBMC DBUS API is still alpha. If you have questions or suggestions please let the community know.

org.openbmc.HostIpmi

The HostIpmi interface allows applications to interact with host processor firmware using IPMI. Typically applications should use the higher level APIs provided by org.openbmc.HostServices to interact with the host processor firmware.

methods

namein signatureout signaturedescription
sendMessageyyyyyayxSend an IPMI message to the host processor firmware.
yIPMI seq.
yIPMI netfn.
yIPMI lun.
yIPMI cmd.
yIPMI cc.
ayIPMI msg.
xThe result status.
setAttentionvoidxRaise an SMS attention event.
xThe result status.

signals

namesignaturedescription
ReceivedMessageyyyyayAn IPMI message was received from the host processor firmware.
yIPMI seq.
yIPMI netfn.
yIPMI lun.
yIPMI cmd.
ayIPMI message.

namespace

pathrequireddescription
/org/openbmc/HostIpmi/<n>Yes on systems with the host-ipmi machine feature, otherwise no.n: IPMI interface number. If implemented, at least one IPMI interface must exist.

org.openbmc.HostServices

The HostServices interface allows applications to interact with the host processor firmware. Applications should use the high level APIs provided here in favor of org.openbmc.HostIpmi where applicable.

methods

namein signatureout signaturedescription
SoftPowerOffvoidxPrepare the host processor firmware for an orderly shutdown.
xThe result status.

namespace

pathrequireddescription
/org/openbmc/HostServicesYes on systems with the host-ipmi machine feature, otherwise no.?

org.openbmc.InventoryItem

The InventoryItem interface allows applications to examine and manipulate information that relates to inventory items.

methods

namein signatureout signaturedescription
setPresentsvoidIndicate the item is present.
strue or false
setFaultsvoidIndicate the item is faulted.
strue or false
updatea{sv}voidUpdate the item attributes.
a{sv}Key/value pair dictionary.

properties

namesignaturedescription
is_frubThe item is field replaceable.
fru_typesThe type of the item.
presentsThe item is physically present.
faultsWhether or not the item is faulted.

namespace

pathrequireddescription
/org/openbmc/inventory/<item>NoInventory items must be instantiated in the inventory namespace.

org.openbmc.NetworkManager

The NetworkManager interface allows applications to examine and manipulate network settings.

methods

namein signatureout signaturedescription
GetAddressTypessQuery the IP address type.
sThe network device to query.
sThe address type for the network device.
GetHwAddressssQuery the hardware address.
sThe network device to query.
sThe hardware address for the network device.
SetAddress4ssssxSet the IPV4 address.
sThe network device on which to set the ipv4 address.
sThe ipv4 address to set.
sThe ipv4 mask to set.
sThe ipv4 gateway to set
xThe result status.
EnableDHCPsxEnable DHCP.
sThe network device on which to enable DHCP.
xThe result status.
SetHwAddressssiSet the hardware address.
sThe network device on which to set the hardware address.
sThe hardware address to set.
iThe result status.
GetAddress4siyssQuery the IPV4 address.
sThe network device to query.
i?
y?
s?
s?

namespace

pathrequireddescription
/org/openbmc/NetworkManager/InterfaceYes on systems with the network machine feature, otherwise no.?

org.openbmc.Sensors

The Sensors interface allows applications to register a sensor instance with a sensor management application.

methods

namein signatureout signaturedescription
registerssvoidRegister a sensor instance of type class.
sThe class name of the sensor.
sThe object path of the sensor.
deletesvoidDeregister a sensor instance.
sThe object path of the sensor.

namespace

pathrequireddescription
/org/openbmc/sensorsYesThe sensor manager must be instantiated here.

org.openbmc.HwmonSensor

The HwmonSensor interface allows applications to query and manipulate hwmon based sensors.

methods

namein signatureout signaturedescription
setByPollv(bv)?
v?
(bv)?

properties

namesignaturedescription
scale??
offset??
filename??

namespace

pathrequireddescription
/org/openbmc/sensors/<class>/<sensor>NoAny sensor instances must be instantiated in the sensors namespace.

org.openbmc.SensorThresholds

The SensorThreshold interface allows applications to query and manipulate sensors thresholds.

methods

namein signatureout signaturedescription
resetThresholdStatevoidvoid?

signals

namesignaturedescription
Emergencyvoid?

properties

namesignaturedescription
thresholds_enabled??
emergency_enabled??
warning_upper??
warning_lower??
critical_upper??
critical_lower??
threshold_state??
worst_threshold_state??

namespace

pathrequireddescription
/org/openbmc/sensors/<class>/<sensor>NoAny sensor instances must be instantiated in the sensors namespace.

org.openbmc.SensorValue

The SensorValue interface allows applications to query and manipulate sensors that only provide a value.

methods

namein signatureout signaturedescription
setValuevvoidSet the sensor value.
vThe value to set.
getValuevoidvGet the sensor value.
vThe sensor value.

properties

namesignaturedescription
unitssThe units associated with the sensor value.
error??

namespace

pathrequireddescription
/org/openbmc/sensors/<class>/<sensor>NoAny sensor instances must be instantiated in the sensors namespace.

org.openbmc.Button

The Button interface allows applications to query the state of buttons.

methods

namein signatureout signaturedescription
isOnvoidbQuery the button state.
bThe button state.
simPressvoidvoidSimulate a button press.
simLongPressvoidvoidSimulate a long button press.

signals

namesignaturedescription
ReleasedvoidThe button was released.
PressedvoidThe button was pressed.
PressedLongvoidThe button was pressed and held.

properties

namesignaturedescription
statebThe current button state.

namespace

pathrequireddescription
/org/openbmc/buttons/<button>NoAny button instances must be instantiated in the buttons namespace.

org.openbmc.control.Bmc

The control.Bmc interface allows applications control the BMC.

methods

namein signatureout signaturedescription
warmResetvoidvoidReset the BMC.

namespace

pathrequireddescription
/org/openbmc/control/bmc<instance>YesAny BMC control instances must be instantiated in the control namespace.

org.openbmc.managers.Download

The managers.Download interface allows applications to receive file download notifications.

signals

namesignaturedescription
DownloadCompletessThe file was downloaded successfully.
sThe file path in the local filesystem.
sThe name of the file that was requested.
DownloadErrorsAn error occurred downloading the file.
sThe name of the file that was requested.

namespace

pathrequireddescription
/org/openbmc/managers/Download??

org.openbmc.control.BmcFlash

The control.BmcFlash interface allows applications update the BMC firmware.

methods

namein signatureout signaturedescription
updateViaTftpssvoidPerform a BMC firmware update using a TFTP server.
sThe ipv4 address of the TFTP server hosting the firmware image file.
sThe name of the file containing the BMC firmware image.
updatesvoidPerform a BMC firmware update with a file already on the BMC.
sThe name of the file containing the BMC firmware image.
PrepareForUpdatevoidvoidReboot BMC with Flash content cached in RAM.
AbortvoidvoidAbort any pending, broken, or in-progress flash update.
ApplyvoidvoidInitiate writing image to flash.
GetUpdateProgressvoidsDisplay progress log Apply phase.
sThe status and log output from Apply

signals

namesignaturedescription
TftpDownloadssA request to download a file using TFTP occurred.
sThe ipv4 address of the TFTP server hosting the firmware image file.
sThe name of the file containing the BMC firmware image.

properties

namesignaturedescription
statussDescription of the phase of the update.
filenamesThe name of the file containing the BMC firmware image.
preserve_network_settingsbPerform a factory reset.
restore_application_defaultsbClear modified files in read-write filesystem.
update_kernel_and_appsbDo not update bootloader (requires image pieces).
clear_persistent_filesbAlso remove persistent files when updating read-write filesystem.
auto_applybAttempt to apply image after unpacking (cleared if image verification fails).

namespace

pathrequireddescription
/org/openbmc/control/flash/bmc??

org.openbmc.control.Chassis

The control.Chassis interface allows applications to query and manipulate the state of a Chassis.

methods

namein signatureout signaturedescription
setIdentityvoidvoidTurn on the identification indicator.
clearIdentityvoidvoidTurn off the identification indicator.
powerOnvoidvoidPower the chassis on.
powerOffvoidvoidPower the chassis off immediately.
softPowerOffvoidvoidPerform a graceful shutdown of the chassis.
rebootvoidvoidReboot the chassis immediately.
softRebootvoidvoidPerform a graceful reboot of the chassis.

properties

namesignaturedescription
uuidsThe chassis UUID.

namespace

pathrequireddescription
/org/openbmc/control/chassis<instance>?Any chassis control instances must be instantiated in the control namespace.

org.openbmc.Flash

The Flash interface allows applications update the host firmware.

methods

namein signatureout signaturedescription
updatesvoidUpdate the host firmware.
sThe file containing the host firmware image.
errorsvoid?
sThe error message.
donevoidvoid?
initvoidvoid?
updateViaTftpssvoidUpdate the host firmware using a TFTP server.
sThe TFTP server url.
sThe file containing the host firmware image.

signals

namesignaturedescription
Updatedvoid?
Downloadss?
sThe TFTP server url.
sThe file containing the host firmware image.

properties

namesignaturedescription
filenames?
flasher_paths?
flasher_names?
flasher_instances?
statuss?

namespace

pathrequireddescription
???

org.openbmc.SharedResource

Insert description of the SharedResource interface here.

methods

namein signatureout signaturedescription
locksvoidLock the shared resource.
sThe shared resource name.
unlockvoidvoidUnlock the shared resource.
isLockedvoidbsGet the lock state of the resource.
bThe lock state.
sThe shared resource name.

properties

namesignaturedescription
lockbThe lock state.
namesThe shared resource name.

org.openbmc.control.Host

The control.Host interface allows applications to manipulate the host processor firmware.

methods

namein signatureout signaturedescription
bootvoidvoidStart the host processor firmware.
shutdownvoidvoidStop the host processor firmware.
rebootvoidvoidRestart the host processor firmware.

signals

namesignaturedescription
BootedvoidThe host processor firmware was started.

properties

namesignaturedescription
debug_modei?
flash_sides?

namespace

pathrequireddescription
/org/openbmc/control/host<instance>NoAny host control instances must be instantiated in the control namespace.

org.openbmc.control.Power

Insert a description of the control.Power interface here.

methods

namein signatureout signaturedescription
setPowerStateivoidSet the power state.
iThe state to enter.
getPowerStatevoidiQuery the current power state.
iThe current power state.

signals

namesignaturedescription
PowerGoodvoidThe power is on.
PowerLostvoidThe power is off.

properties

namesignaturedescription
pgoodi?
statei?
pgood_timeouti?

namespace

pathrequireddescription
/org/openbmc/control/power<instance>?Any power control instances must be instantiated in the control namespace.

org.openbmc.Led

Insert a description of the Led interface here.

methods

namein signatureout signaturedescription
setOnvoidvoidTurn the LED on.
SetOffvoidvoidTurn the LED off.
setBlinkSlowvoidvoidBlink the LED slowly.
setBlinkFastvoidvoidBlink the LED quickly.

properties

namesignaturedescription
coloriThe color of the LED.
functions?
statesThe current LED state.

namespace

pathrequireddescription
/org/openbmc/control/led/<led>NoAny LED instances must be instantiated in the control/led namespace.

org.openbmc.objectmapper.ObjectMapper

The ObjectMapper interface enables applications to discover the DBUS unique connection name(s) for a given object path.

methods

namein signatureout signaturedescription
GetObjectsa{sas}Determine the DBUS unique connection name(s) implementing a single object and the interfaces implemented by those services.
sThe path of the object to query.
a{sas}A dictionary with DBUS unique connection names as keys, and interfaces as values.
GetAncestorssa{sa{sas}}Determine the DBUS unique connection name(s) implementing any ancestor objects and the interfaces implemented by those services.
sThe point in the namespace from which to provide results.
a{sa{sas}}A dictionary of dictionaries, with object paths as outer keys, DBUS unique connection names as inner keys, and implemented interfaces as values.
GetSubTreesia{sa{sas}}Determine the DBUS unique connection name(s) implementing an entire subtree of objects in the DBUS namespace.
sThe point in the namespace from which to provide results.
iThe number of path elements to descend.
a{sa{sas}}A dictionary of dictionaries, with object paths as outer keys, DBUS unique connection names as inner keys, and interfaces implemented by those services as values.
GetSubTreePathssiasList all known DBUS objects.
sThe point in the namespace from which to provide results.
iThe number of path elements to descend.
asAn array of object paths.

namespace

pathrequireddescription
/org/openbmc/objectmapper/objectmapperYesThe object mapper must be instantiated here.

org.openbmc.recordlog

Insert a description of the record log interface here.

methods

namein signatureout signaturedescription
acceptHostMessagesssayqAccept a message from the host processor firmware.
sThe message content.
sThe message severity.
sAn association between the message and another entity.
ayDevelopment data associated with the message.
qThe created record ID.
clearvoidqRemove all record instances.
q?

namespace

pathrequireddescription
/org/openbmc/records/<class>NoAny recordlog instances must be instantiated in the records namespace.

org.openbmc.record

Insert a description of the record interface here.

properties

namesignaturedescription
messagesA free from message.
severitysThe record severity.
reported_bysThe originating entity of the record.
timesThe timestamp associated with the record.
debug_dataayDevelopment data associated with the record.

namespace

pathrequireddescription
/org/openbmc/records/<class>/<record>NoRecords must be instantiated in the records namespace.

org.openbmc.Object.Delete

Applications that create objects that can be removed for any reason must implement this interface. Some common examples of this could be an event log instance or a user account instance.

methods

namein signatureout signaturedescription
deletevoidvoidRemove the object from the DBUS namespace.

org.openbmc.Associations

Applications wishing to create an association between two or more objects implement can this interface. Associations exist to provide a stable but extendable DBUS API.

properties

namesignaturedescription
associationsa(sss)An array of forward, reverse, endpoint tuples.
sThe type of association to create.
sThe type of association to create for the endpoint.
sThe object path of the endpoint.

For example, given an object /org/openbmc/events/1 that implements org.openbmc.Associations and then sets the associations property to:

"associations": [
  ["events", "frus", "/org/openbmc/piece_of_hardware"],
  ["events", "times", "/org/openbmc/timestamps/1"]
]

would result in the following associations:

/org/openbmc/events/1/frus
/org/openbmc/events/1/times
/org/openbmc/piece_of_hardware/events
/org/openbmc/timestamps/1/events

org.openbmc.Association

Applications use this interface to inject associations into the DBUS namespace.

properties

namesignaturedescription
endpointsasAn array of association endpoints.

For example, given:

"/org/openbmc/events/1/frus": {
    "endpoints": [
        "/org/openbmc/hardware/cpu0",
        "/org/openbmc/hardware/cpu1",
    ]
}

Denotes the following:

/org/openbmc/events/1 => fru => /org/openbmc/hardware/cpu0
/org/openbmc/events/1 => fru => /org/openbmc/hardware/cpu1

org.openbmc.settings.Host

The settings.Host interface provides a basic settings repository for host processor firmware settings.

methods

Host settings are accessed using the standard org.freedesktop.DBus.Properties interface.

signals

Applications are notified of host setting changes using the standard org.freedesktop.DBus.ObjectManager interface.

properties

Settings are accessed using the standard org.freedesktop.DBus.Properties interface.

namespace

pathrequireddescription
/org/openbmc/settings/host<instance>NoAny host settings instances must be instantiated in the settings namespace.

org.openbmc.Watchdog

The Watchdog interface enables health monitoring applications to offload timer bookeeping to another application.

methods

namein signatureout signaturedescription
startvoidvoidStart the countdown timer.
pokevoidvoidPing the watchdog.
stopvoidvoidStop the countdown timer.
setivoidSet the timer interval.
iThe timer interval.

signals

namesignaturedescription
WatchdogErrorvoidThe watchdog was not pinged before the timer expired.*

namespace

pathrequireddescription
/org/openbmc/watchdog/<watchdog>NoAny watchdog instances must be instantiated in the watchdog namespace.