public interface DriverService
DriverService
is the interface that all OpenMUC communication drivers have to implement and register
as a service in the OSGi environment. The OpenMUC Core Data Manager tracks this service and will therefore be
automatically notified of any new drivers in the framework. If sampling, listening or logging has been configured for
this driver, then the data manager will start right away with the appropriate actions.
A driver often implements a communication protocol but could also get its data from any other source (e.g. a file).
Some guidelines should be followed when implementing a driver for OpenMUC:
debug
or trace
. Even these debug messages should be
used very sparsely. Only use them to further explain errors that occur.ConnectionException
. The framework will then
try to reconnect by calling the connect
function.DriverService
are caught by the OpenMUC framework and logged
with level error
. It is bad practice to throw these unchecked exceptions because they can clutter the
log file and slow down performance if the function is called many times. Instead the appropriate Flag should be
returned for the affected channels.Modifier and Type | Method and Description |
---|---|
Connection |
connect(java.lang.String deviceAddress,
java.lang.String settings)
Attempts to connect to the given communication device using the given settings.
|
org.openmuc.framework.config.DriverInfo |
getInfo()
Returns the driver information.
|
void |
interruptDeviceScan()
A call of this function signals the driver to stop the device scan as soon as possible.
|
void |
scanForDevices(java.lang.String settings,
DriverDeviceScanListener listener)
Scans for available devices.
|
org.openmuc.framework.config.DriverInfo getInfo()
void scanForDevices(java.lang.String settings, DriverDeviceScanListener listener) throws java.lang.UnsupportedOperationException, org.openmuc.framework.config.ArgumentSyntaxException, org.openmuc.framework.config.ScanException, org.openmuc.framework.config.ScanInterruptedException
deviceFound()
function. Optionally this method may occasionally call the
updateScanProgress function of DeviceScanListener. The updateScanProgress function should pass the progress in
percent. The progress should never be explicitly set to 100%. The caller of this function will know that the
progress is at 100% once the function has returned.settings
- scanning settings (e.g. location where to scan, baud rate etc.). The syntax is driver specific.listener
- the listener that is notified of devices found and progress updates.java.lang.UnsupportedOperationException
- if the method is not implemented by the driverorg.openmuc.framework.config.ArgumentSyntaxException
- if an the settings string cannot be understood by the driverorg.openmuc.framework.config.ScanException
- if an error occurs while scanningorg.openmuc.framework.config.ScanInterruptedException
- if the scan was interrupted through a call of interruptDeviceScan()
before it was done.void interruptDeviceScan() throws java.lang.UnsupportedOperationException
java.lang.UnsupportedOperationException
- if the method is not implemented by the driverConnection connect(java.lang.String deviceAddress, java.lang.String settings) throws org.openmuc.framework.config.ArgumentSyntaxException, ConnectionException
Connection
interface. The framework will then call read/write
etc functions on the returned connection object. If the syntax of the given deviceAddresse, or settings String is
incorrect it will throw an ArgumentSyntaxException
. If the connection attempt fails it throws a
ConnectionException
.
Some communication protocols are not connection oriented. That means no connection has to be build up in order to
read or write data. In this case the connect function may optionally test if the device is reachable.deviceAddress
- the configured device address.settings
- the settings that should be used for the communication with this device.org.openmuc.framework.config.ArgumentSyntaxException
- if the syntax of the deviceAddress or settings string is incorrect.ConnectionException
- if the connection attempt fails.