Device Statuses

The goal of this section is to describe the concept of a device status in Device Access. Further down, the information is separated into two main sections: Details for Controllers and Details for End Devices. Devices are used to represent two different types of physical devices. The first type is controllers (USB sticks or a gateway) that allow access to a specific network protocol. The second type are the actual end devices such as dimmers, switches, motion detectors, etc.

Device Statuses

The DeviceStatus - com.prosyst.mbs.services.da.DeviceStatus, defines the status of the device. Keep in mind that these statuses have different meanings depending on whether they are for a device that represents a controller, or a device that represents an end device. Only part of these statuses are used for controllers. The possible device statuses are:

Device status	Description
INITIALIZING	In the case of controllers, indicates that the list of available devices is attempted to be read by the controller. In the case of an end device, indicates that the device is in the process of initialization. It needs a little bit of time to change the status, for example to ONLINE.
ONLINE	In the case of controllers, indicates that the controller is working properly. In the case of an end device, indicates that there are no known problems with the end device and that the recent communication with the device has been passed through. The device should be available for further user interaction.
NOT_CONFIGURED	Indicates that the device is not configured. It is not offline, it is available. Possibly, the device needs an additional user action to get configured.
OFFLINE	In the case of controllers, indicates that the controller is unplugged, or that there is no connection to the controller. In the case of an end device, indicates that the recent communication with the device has failed. The device will not be available for further interaction.
NOT_INITIALIZED	Indicates that the data representing the end device is not read properly or is incorrect. This status is not used in the case of controllers.
FIRMWARE_UPDATING	Indicates that the device is starting a firmware download. This status will be set just before the download and will change right after the upgrade.
REMOVING	Indicates that device removal from the system is in place. The device status will change before the device removal and will be set to REMOVED, when the removal is complete.
REMOVED	Indicates that the device is removed from the system. This status is only used by the application to keep an instance of an old device that is no longer active.

Device Errors

A number of common error codes for devices are defined by com.prosyst.mbs.services.da.DeviceError. Keep in mind that there are error codes only in the OFFLINE, NOT_INITIALIZED, ONLINE and NOT_CONFIGURED statuses. The role of an error code is to indicate the reason why a device is put in the OFFLINE, NOT_INITIALIZED or NOT_CONFIGURED statuses, and if there was some problem on the last communication in ONLINE status. The possible device error codes are:

Device error	Description
DEVICE_NOT_ACCESSIBLE	In the case of controllers, indicates that the controller is unplugged, or that the connection to the controller is lost. It is possible to check if a related peripheral to the device is available, to see if the controller was unplugged. In the case of an end device, indicates that the end device is not accessible anymore. For example, driver does not return info for the end device after the controller is plugged. Another example is, the adapter bundle is installed, but there is no service for the controller from the driver. It is used only in the OFFLINE status.
DEVICE_BROKEN	Indicates that the controller or end device is broken. It is used only in the OFFLINE status.
DEVICE_DATA_INSUFFICIENT	Indicates that the data read from the end device is not enough. The device can not be determined. It is used only in the NOT_INITIALIZED status.
DEVICE_COMMUNICATION_ERROR	Indicates that there is an error when a protocol command is sent to the end device. It is used in the ONLINE and in the NOT_INITIALIZED statuses.
NO_PROTOCOL_ADAPTER	Indicates that there is no protocol adapter. For example, if a controller is unplugged the driver component for this controller will be uninstalled after some timeout. It is used only in the OFFLINE status.
IN_DUTY_CYCLE	Indicates that the controller or the end device is in duty cycle. It is used only in the OFFLINE status.
CONFIGURATION_NOT_APPLIED	Indicates that the configuration is not applied, or only part of the configuration is applied to the physical device. It is used only in the NOT_CONFIGURED status.
CONFIGURATION_NOT_VALID	Indicates that the configuration is not valid. It is used only in the NOT_CONFIGURED status.
DEVICE_REMOVED_LOCALLY	Indicates that the device is removed locally. It is used only in the OFFLINE status.

Device Status Events

When a device status is changed, Device Access generates an event in the EventAdmin. This event is always generated after the status is already changed. The event has a topic FunctionalItemEventConstants.TOPIC_PROPERTY_CHANGED for the event device property status.

Behavior of Methods Based on Device Status

The device status will be set to ONLINE after its Device Items have been registered. The Device Item methods (Functional Item methods) - setName(String) and setTags(Set<String>) will not trow an exception no matter the device status. Only in the REMOVED device status, the provided parameter value will be skipped.

If the communication with the Device Item is not possible (it is INITIALIZING or not NOT INITIALIZED), the DeviceItemNotInitializedException will be thrown for setter, getter or operation Device Item methods.

In all statuses (except REMOVED) get property of Device Item will succeed if there is already a cached value in Property Cache or a persistent value. If there is no cached value, an exception will be thrown. The set property and operation Device Item methods of devices may succeed, or throw an exception. The set property and operation Device Item methods of Device Item will also throw IlegalArgumentException if the parameters are invalid.

Status	Method Behavior
REMOVED	The setter, getter or operation methods of Device Item do not need to be called. In this status Device Item getter methods will throw an IllegalStateException.
OFFLINE	If Device Item properties are not yet cached, getter methods will throw an exception, otherwise will return the cached or persistent value. The setter and operations methods of Device Item do not need to be called in this status.
INITIALIZING	If Device Item properties are not yet cached, getter methods will throw an exception. The operations and set properties Device Item methods can also be called. They can succeed or throw an exception.
NOT_INITIALIZED	The setter, getter or operation methods of Device Item can be called. They can succeed or can throw an exception.
NOT_CONFIGURED	The setter, getter or operation methods of Device Item can be called. They can succeed or can throw an exception.
ONLINE	The setter, getter or operation methods of Device Item can be called. They can succeed or can throw an exception.
REMOVING	The setter, getter or operation methods of Device Item can be called. They can succeed or can throw an exception.
FIRMWARE_UPDATES	The setter, getter or operation methods of Device Item can be called. They can succeed or can throw an exception.

Details for Controllers

When a controller is plugged for the first time it enters the INITIALIZING status. A device list is attempted to be read by the controller.

Status Transitions for Controllers

From/To	OFFLINE	INITIALIZING	ONLINE	NOT_CONFIGURED	REMOVING	REMOVED	FIRMWARE_UPDATING
OFFLINE	N/A	Controller is plugged or discovery procedure is started in Device Access. Discovered devices are read by the controller.	Controller is out of duty cycle. In general this transition is possible only if no command is sent to the controller, otherwise the transition will be to INITIALIZING.	Controller changes the status to ONLINE but there was an error when Device Access was configuring the controller.	Remove operation is invoked in Device Access.	Exit status	Firmware procedure is started.
INITIALIZING	Duty cycle is reached. Controller is unplugged. Some driver bundle is stopped or uninstalled.	Reading of device list is done.	Controller changes the status to ONLINE but there was an error when Device Access was configuring the controller.	Remove operation is invoked in Device Access (but only an offline controller can be removed).	Remove operation is invoked in Device Access (but only an offline controller can be removed).	Exit status	Firmware procedure is started.
ONLINE	Duty cycle reached. Controller is unplugged. Some driver bundle is stopped or uninstalled.	Explicit discovery procedure is started in Device Access. Discovered devices are read by the controller.	N/A	There is an error when Device Access is applying the configuration on the controller device.	Remove operation is invoked in Device Access (but only an offline controller can be removed).	Exit status	Firmware procedure is started.
NOT_CONFIGURED	Duty cycle reached. Controller is unplugged. Some driver bundle is stopped or uninstalled.	Explicit discovery procedure is started in Device Access. Discovered devices are read by the controller.	Device Access is applying correctly the configuration on to the controller device.	N/A	Remove operation is invoked in Device Access (but only an offline controller can be removed).	Exit status	Firmware procedure is started.
REMOVING	The invoked remove operation cannot be performed.	The invoked remove operation cannot be performed.	The invoked remove operation cannot be performed.	The invoked remove operation cannot be performed.	N/A	Successfully executed the remove operation.	Firmware procedure is started.
REMOVED	N/A	N/A	N/A	N/A	N/A	N/A	N/A
FIRMWARE_UPDATING	Firmware updating is finished and returned to the OFFLINE status.	Firmware updating is finished and returned to the INITIALIZING status.	Firmware updating is finished and returned to the ONLINE status.	Firmware updating is finished and returned to the NOT_CONFIGURED status.	Remove operation is invoked in Device Access (but only an offline controller can be removed).	Exit status	N/A

Details for End Devices

When a new end device is paired for the first time it enters the INITIALIZING status. Data to represent the device is attempted to be read. Device Item properties are initially attempted to be read and put in the Property Cache.

Status Transition for End Devices

From/To	OFFLINE	INITIALIZING	NOT_INITIALIZED	NOT_CONFIGURED	ONLINE	REMOVING	REMOVED	FIRMWARE_UPDATING
OFFLINE	N/A	Controller is plugged or discovery procedure is started in Device Access. Discovered devices are read by the controller.	N/A	Duty cycle left and previous status was NOT_CONFIGURED, or the end device changes the status to ONLINE but there was error when Device Access is configuring the end device.	Duty cycle left. Specific protocol mechanism which indicates that the device is reachable.	Remove operation is invoked in Device Access.	N/A	Firmware procedure is started.
INITIALIZING	Duty cycle reached. Controller device is OFFLINE. Specific protocol mechanism which indicates that the device is unreachable.	N/A	Error found during reading or processing data needed to represent the device.	Device has configuration pending, or the end device changes the status to ONLINE but there was an error when Device Access is configuring the end device.	Data to represent the device is read with no errors. Device Item properties are initially read and put in the Property Cache.	Remove operation is invoked in Device Access.	N/A	Firmware procedure is started.
NOT_INITIALIZED	Duty cycle reached. Controller device is OFFLINE. Specific protocol mechanism which indicates that the device is unreachable.	Controller is plugged or discovery procedure is started in Device Access. Discovered devices are read by the controller.	N/A	N/A	N/A	Remove operation is invoked in Device Access.	N/A	Firmware procedure is started.
ONLINE	Duty cycle reached. Controller device is OFFLINE. Specific protocol mechanism which indicates that the device is unreachable.	Controller is plugged or discovery procedure is started in Device Access. Discovered devices are read by the controller.	N/A	New configuration is applied to the device.	N/A	Remove operation is invoked in Device Access.	N/A	Firmware procedure is started.
NOT_CONFIGURED	Duty cycle reached. Controller device is OFFLINE. Specific protocol mechanism which indicates that the device is unreachable.	Controller is plugged or discovery procedure is started in Device Access. Discovered devices are read by the controller.	N/A	N/A	Button is pushed on the device to apply the configuration.	Remove operation is invoked in Device Access.	N/A	N/A
REMOVING	The invoked remove operation cannot be performed.	The invoked remove operation cannot be performed.	The invoked remove operation cannot be performed.	The invoked remove operation cannot be performed.	The invoked remove operation cannot be performed.	N/A	Remove operation is successfully executed.	Firmware procedure is started.
REMOVED	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A
FIRMWARE_UPDATING	Firmware updating is finished and returned to the OFFLINE status.	Firmware updating is finished and returned to the INITIALIZING status.	Firmware updating is finished and returned to the NOT_INITIALIZED status.	N/A	Firmware updating is finished and returned to the ONLINE status.	Remove operation is invoked in Device Access.	N/A	N/A