The Device Admin guide details on how to create a Device with a set of functionalities. Below you will found information from the Device Item abstraction perspective.

The Device Item (com.prosyst.mbs.services.fim.FunctionalItem) represents the functionality of the Device. It has set of properties and operations that bring the real physical access to the Device functionalities. Every Device Item is a Functional Item and it is registered as an OSGi service. Each Device may have zero or more Device Items attached to it. The Device Access defines the common items interfaces.
The Device Access provides a mapping mechanism which is applied to the Device Items. This means that Device Access enables you to construct your own Device Item which can be mapped to the Device Item that is provided by the protocol adapter. You can learn more about it and how you can do it on Overview page.

Retrieving a Device Item

The Device Access provides two ways by which you can retrieve a Device Item. The following description gives you more information and examples about the ways. First you should have available device with some functionalities.

Retrieving a Device Item Using Service Registry

Each Device Item is registered as a service in an OSGi registry. In this way for retrieving a Device Item you should call the BundleContext.getServiceReferences(Class<?>, String) method, where:

• The first parameter of this method is the class registered under the Device Item. For example when you retrieve the Device Items this class will be FunctionalItem.class.
• The second parameter of this method is LDAP filter. In this LDAP filter you might include all registration properties of the Device Item. The next section describe them. Here it is important to note that it is a good practice, to filter Device Items by FunctionalItem.NAME or FunctionalItem.TAGS instead of FunctionalItem.UID. The UID of the Device Item is identifier in the system. The name of the Device Item is identifier for the user.

The following example shows how to retrieve the Device Item with name "test:device:item:name". For this reason you should have created Device with any Device Item.

Collection<ServiceReference<FunctionalItem>> items = bc.getServiceReferences(StepperMotor.class, '(' + FunctionalItem.NAME + "=test:device:item:name))");

When the Device Item is in the OSGi registry this ensures that the Device Item is available and you can access it. If the protocol adapter is unregistered, the Device Items that was provided from it, should be unregistered from the OSGi registry also. In this situation the Device is in status of offline.

Retrieving a Device Item Using the so-Called Local Device Methods

You can use this methods of the Device to retrieve a Device Item. You should be careful with using these methods because when you get the Device Item, it may not be available for use. It is recommended to get the Device Item from the service registry (see above).

• Set<FunctionalItem> getItems() – this method returns a Set of FunctionalItem supported by the Device. The protocol adapter may add or remove functional items runtime of already existing device. The following example shows how to use this method. First you should have an available Device with Device Item.

  private Set<FunctionalItem> getDeviceItems() {

    Device device = createDevice();

    Set<FunctionalItem> items = device.getItems();

    for (FunctionalItem item : items) {

      System.out.println("Device Item Object Class: " + item.getObjectClass());

      System.out.println("Device Item UID : " + item.getUID());

      System.out.println("Device Item Name: " + item.getName());

      System.out.println("Device Item Tags: " + item.getTags());

      System.out.println("Device Item Attributes: " + item.getAttributes());

    }

    return items;

  }

• Set<FunctionalItem> getItems(String) - this method return a Set of FunctionalItem that implement the defined object class as a parameter of this method. The protocol adapter is possible to add or remove functional items runtime of already existing Device. The following example shows how to use this method. First you should have an available Device with Device Item.

  private Set<FunctionalItem> getDeviceItemsByClassName() {

    Device device = createDevice();

    Set<FunctionalItem> items = device.getItems(MotionDetector.class.getName());

    for (FunctionalItem item : items) {

      System.out.println("Device Item Object Class: " + item.getObjectClass());

      System.out.println("Device Item UID : " + item.getUID());

      System.out.println("Device Item Name: " + item.getName());

      System.out.println("Device Item Tags: " + item.getTags());

      System.out.println("Device Item Attributes: " + item.getAttributes());

    }

    return items;

  }

• <T> Set<T> getItems(Class<T>) - this method return a Set of <T> (type of the required items) that implement the defined object class as a parameter of this method. The protocol adapter is possible to add or remove functional items runtime of already existing Device. The following example shows how to use this method. First you should have an available Device with Device Item. In this example the parameter <T> is MotionDetector.

  private Set<MotionDetector> getDeviceItemsByClass() throws IOException {

    Device device = createDevice();

    Set<MotionDetector> motionDetectors = device.getItems(MotionDetector.class);

    for (MotionDetector motionDetector : motionDetectors) {

      System.out.println("The Motion Detector sensitivity is: " + motionDetector.getSensitivity());

    }

    return motionDetectors;

  }

Registration properties

The following table describes the Device Item registration properties:

DeviceItem attributes

Functional properties and operations

Each Device Item is a FunctionalItem that represents the functionalities of the Device. Each Device Item implements some functional interface. Each functional interface has set of functional properties and operations. More about how to define your Functional Item and whats are the restriction when you write a Functional Item, you can found on Functional Item Developer Guide - Defining Functional Items page.

• Functional properties

The Device Item may define functional properties. You can get information about defined Device Item properties by using the FunctionalItem.getItemMetadata() method. It returns com.prosyst.mbs.services.fim.metadata.ItemMetadata that holds Map<String, PropertyMetadata>. You can learn more about the metadata on Functional Item Developer Guide - Metadata and Annotations page. These Device Items that have readable properties are registered in the OSGi registry after initialization of internal cache.

Operations

The Device Item may define operations to be executed over a Device Item. You can get information about defined Device Item operations by using the FunctionalItem.getItemMetadata() method. It returns com.prosyst.mbs.services.fim.metadata.ItemMetadata that holds Map<String, OperationMetadata>. For more details about the metadata refer to Functional Item Developer Guide - Metadata and Annotations page.