Integration with Orion: kurento-fiware java module¶

The Kurento team has developed a small module that you can use in your own application and it would make it easier to connect with Orion, and make use of it in order to gather the context generated by your application related with kurento (MediaEvents and Devices). Also it has been designed to be easily extended so you can implement your own publishers and readers for any other entity.

How to use it¶

Clone the gitHub repository.

git clone https://github.com/Kurento/kurento-fiware-java.git

Go to the project kurento-fiware (the other folder contains an example of how to use it).
```
cd kurento-fiware
```
Build and install in your maven local repo (you will need Java >= 1.8).
```
mvn install
```

Import in your project the dependency

<dependency>
    <groupId>org.kurento</groupId>
    <artifactId>kurento-fiware</artifactId>
    <version>2.0-SNAPSHOT</version>
</dependency>

Processing Media Streams¶

Any Media Stream that flows in Kurento can be processed by one or more modules. Some modules would rise Media Events following the logic they are meant to with associated information. For example, the built-in module “kms-platedetector” would rise a Media Event whenever a traffic plate is detected, this event would contain the plate number read from the Media Stream. This Events should be collected by the client application an the application should act upon them.

Kurento Events¶

You can configure to receive Kurento Events into your client application and extract relevant context information that can be fed to Orion.

Example:

You develop a Client Application with a Kurento attached and the kms-platedetector built-in module. Each time a traffic plate is detected , Kurento rises a Event and your application reacts by:

Inserting the Event as a MediaEvent in Orion.
Looking for the plate in Orion, and update the location of the vehicle associated.

MediaEvents to Orion¶

MediaEvent is a generic FIWARE DataModel (still under approval process) that allows any application using Kurento to insert in Orion any type or Kurento Event risen by any module If you are using Java for implementing your client application you can use kurento-fiware module to simplify all the integration.

While using the provided library you need just to:

Configure the connection to the Orion instance by:
```
final OrionConnectorConfiguration orionConnectorConfiguration = new OrionConnectorConfiguration();
```
By default the configuration points to http://localhost:1026

Define how to exactly match the detected Event to the MediaEvent DataModel extending the MediaEventPublisher defining a mapEntityToOrionEntity. E.g.

public MediaEvent mapEntityToOrionEntity(DevicePlateDetectedEvent kurentoEvent) {
  MediaEvent orion_entity = new MediaEvent();
  orion_entity.setId(...);
  orion_entity._getGsmaCommons().setDateCreated(kurentoEvent.getTimestamp());
  orion_entity.setData(kurentoEvent.getPlate());
  if (kurentoEvent.getCamera() != null) {
    orion_entity.setDeviceSource(kurentoEvent.getCamera().getId());
  }
  orion_entity.setMediasource(mapKurentoMediaSource(kurentoEvent.getSource()));
  return orion_entity;
}

And publish the event.

plateDetectedEventPublisher.publish(extendedEvent);

You can check the specifics of the MediaEvent DataModel here.

Devices¶

The cameras used for generating the Media Streams are also part of the context so we expect them to be also part of the information that can be found in Orion. Devices are an an integral part of the common entities found in Orion and they are defined as a very generic FIWARE DataModel, so any kind of “camera” used in the Kurento Client application can be represented in this DataModel.

If your Client Kurento Application is developed in Java you can also make use of the provided kurento-fiware module to simplify all the integration.

The essential steps for inserting Devices into Orion are similar to the Media Events’ ones:

Configure the connection to the Orion instance by:
```
final OrionConnectorConfiguration orionConnectorConfiguration = new OrionConnectorConfiguration();
```
By default the configuration points to http://localhost:1026

Define how to exactly match the custom Camera used in the application to the Device DataModel extending the DevicePublisher defining a mapEntityToOrionEntity. E.g.

public Device mapEntityToOrionEntity(Camera cam) {

  String[] supportedProtocol = { "WebRTC" };

  Device entity = new Device();

  entity.setControlledAsset(cam.getControlledAsset());
  entity.setDateInstalled(cam.getCreationDate());
  entity.setDeviceState(cam.getState());
  entity._getDeviceCommons().setSupportedProtocol(supportedProtocol);
  entity._getGsmaCommons().setId(cam.getId());
  entity._getGsmaCommons().setDateCreated(cam.getCreationDate());
  entity._getGsmaCommons().setDescription("Plate detector camera example");
  entity._getGsmaCommons().setName(cam.getName());
  entity.setIpAddress(cam.getIp());
  return entity;
}

Publish the Device.

CamPublisher cameraPublisher = new CamPublisher(orionConnectorConfiguration);
cameraPublisher.publish(cam);

Update the Device for each change of state (e.g. “PAUSED” / “PROCESSING”) or each last value detected.

final OrionConnectorConfiguration orionConnectorConfiguration = new OrionConnectorConfiguration();
CamPublisher cameraPublisher = new CamPublisher(orionConnectorConfiguration);
CamReader cameraReader = new CamReader(orionConnectorConfiguration);
Camera cam = cameraReader.readObject(id);
/* Update values of cam */
cameraPubliser.update(cam);

Other entities¶

While developing your Smart Solution you would need to work with other Entities in Orion, for example Vehicles, Alerts, places such as museums, gardens, etc. While Kurento Entities aren’t directly related to these, the kurento-fiware module, provides an easy way of extending its functionality to any other DataModel and any other custom Object.

In this case you can replicate the structure that the module provides for the Device and MediaEvent entities in your project. This means to provide the following classes:

YourOrionEntity.java: That is the class to map the OrionEntity you need. This class must implement the OrionEntity Interface.
<YourOrionEntity>OrionPublisher.java: This needs to be an extension of the DefaultOrionPublisher. You will need to define:
- O: the OrionEntity that will be published in orion in this case <YourOrionEntity>.
- T: a custom class that can be mapped to <YourOrionEntity>.
- mapEntityToOrionEntity is the method that would be able to map from T to O.
<YourOrionEntity>OrionReader.java: This needs to be an extension of the DefaultOrionReader. As for the publisher you will need to define:
- O: the OrionEntity that will be published in orion in this case <YourOrionEntity>.
- T: a custom class that can be mapped to <YourOrionEntity>.
- mapOrionEntityToEntity; is the method that would be able to map from O to P.

In case YourOrionEntity needs some processing for presenting a plain JSON to Orion or for reading it you may need to provide also a <YourOrionEntity>JsonManager to the OrionConnector.

More¶

Follow the links for more information about the kurento-fiware module: