Home > Libris Platform Overview

The Libris Platform consists of all the services that communicate with the Libris devices, the phone carriers, location based services, and other web applications / services to provide the Libris solution to our customers and partners. We offer multiple ways for you to interact with the platform so you can start simple by using our Numera web applications, or fully integrate our platform into your own applications using the API.

Libris Device

It all begins with the device. For the purpose of understanding the API, the device can be thought of as a simple 3G cellphone which is capable of making voice calls and transmitting data using standard internet web service calls.

Each Libris device has 4 attributes that are unique to that device, each one can be used to locate a device in our platform:

• IMEI: unique id that is associated with the radio hardware inside of the device
• ICCID: unique id for the SIM card embedded in the device
• DeviceId: Numera's internal identifier for the device
• Device Name: a unique name that you can assign to the device, as your own identifier

Understanding Realms

When the devices leave our factory, they are already defined in our platform as belonging to a customer. A customer in our platform is referred to as a realm. A realm is a way for us to organize a population of devices and all of the settings and rules related to those devices, such as which phone numbers the device should call in an emergency, which events should get published, and where and how those events are published. Realms are also used for security so we can make sure only certain users and applications have access to certain devices.

When you begin your implementation project, you will be assigned a master realm name that will be the default for your implementation. If you have other organizations that need to manage a subset of your devices, we can create sub-realms within your master realm so that you can assign devices into those sub-realms without giving those other organizations control of all of your devices. These sub-realms can contain multiple levels of other sub-realms (sub-realms of sub-realms) allowing you to design hierarchical levels of access to devices and configuration settings.

In the image above, users at the Contoso realm level have access to all devices, even if they are in the Contoso.DealerB.SubDealer realm. Users in the Contoso.DealerA realm only have access to devices in that realm.

Understanding Configuration Settings

Our devices and platform utilize a variety of configuration settings to determine the behavior of a device, from whether fall detection is enabled, to the phone numbers they call in an emergency, to how loud our audio messages play. All of these settings live in a hierarchical data store that allows you to define setting values at a master realm level, and have them cascade down to sub-realms, or be overridden - down to an individual device level.

The hierarchy begins with our system level settings (defined by Numera), then it cascades down through all the realms related to a device, and ends with the device. We will use the following table of settings to walk through a few examples of how the configuration settings effect the behavior of devices.

Example: Device at master realm level

For this example, we have a device in the Contoso realm with no device overrides. Based on our example settings, this device would see this unified list of settings:

power.heart_beat_interval = 30 (from System)
audio.master_volume = 100 (from System)
location.gps_sample_interval = 600 (from Contoso realm)
ecsm.disable_call_cancel = true (from Contoso realm)

Example: Device at sub-realm level with override

For this example, we have a device in the Contoso.DealerB realm with an override defined for audio.master_volume=50. Based on our example settings, this device would see this unified list of settings:

location.gps_sample_interval = 600 (from Contoso realm)
ecsm.disable_call_cancel = true (from Contoso realm)
power.heart_beat_interval = 20 (from Contoso.DealerB realm)
audio.master_volume = 50 (from device override)

Example: Device at lowest level realm with override

For this example, we have a device in the Contoso.DealerB.SubDealer realm with an override defined for audio.master_volume=30. Based on our example settings, this device would see this unified list of settings:

location.gps_sample_interval = 600 (from Contoso realm)
ecsm.disable_call_cancel = false (from Contoso.DealerB.SubDealer realm)
power.heart_beat_interval = 30 (from Contoso.DealerB.SubDealer realm)
audio.master_volume = 30 (from device override)

Libris Events

At its core, our platform is an event collection and publishing platform. Every Libris device in the field generates a variety of events (or signals for those of you with monitoring centers), from location and status updates to emergency calls. All of these events are captured by the platform and routed to the various services that know how to process those events. You have the ability to determine whether your platform wants to subscribe to all, some, or none of these events as part of your implementation using an event receiver. Events can be sent to more than one endpoint, and are configured and shared at a realm level, similar to the configuration settings.

The device does not transmit all events all of the time. Generally the device will store generated events in a queue that gets transmitted when the device is placed in a charger, a phone call is placed (for a fall or the user presses the button), or thresholds are crossed for certain types of events controlled by configuration (such as 2 hours worth of location updates). In the charger, the device will wake up periodically and transmit any events it has in its queue. There are certain events, such as low battery and low activity alarms which do get transmitted as soon as they are generated.

Events do have various states, but in general most events have a state of "Closed" which means they will not be updated. Some events, such as Classify or Normal events are initially created and then updated for a period of time, and then either "Cancelled" or "Closed" to indicate their final state. Updates to these events are sent to your event receiver, so it is important in your own design to remember that you will receive data for an existing event as an update in certain situations.

Event Collector (a.k.a. Patient)

Libris events are not stored with the Libris device record in our platform, instead they are associated with and stored with something we call an Event Collector. An Event Collector can be thought of as the Patient record for the person wearing the Libris.

A Libris can be assigned to different people throughout its lifetime, therefore events are stored with those records so that one patient's event history does not intermingle with another. When you re-assign a Libris to a new user, we create a new Event Collector for the device and begin storing new events in this location.

Device Lifecycle

The best way to explain the overall platform and how all of the various components communicate and fit together is to walk through the lifecycle and typical use cases for a Libris Device. We will begin by explaining what happens with a device once it leaves our manufacturing facility.

At the Factory

When your organization orders a Libris device our factory is notified of the number of units to manufacture and which customer they belong to. Each device contains a unique id associated to the radio in the device (the IMEI) and an id related to the SIM card (the ICCID) that is inserted into the device during the manufacturing process. The factory keeps track of the IMEI and ICCID for each device and creates a file containing this information for the order.

Once the order leaves the factory, a manifest file is created that contains a detailed list of all of this information. We can send you a copy of this manifest so that your organization can process the file and pre-populate your own databases with the IMEI numbers before the units arrive at your location, or you can just wait until the devices arrive and scan the barcodes on the boxes.

Numera has programs that parse the manifest files and load the devices into our platform. When they are initially loaded our platform creates a unique DeviceId for the device, places it in the master realm associated with your organization, and places the device in an "unmanaged" state. While the Libris devices are being shipped they are not activated with the carrier yet, and if they accidentally powered on during transit they would not attempt to activate.

It is important to note that there are no events created during this process as there is currently no Event Collector associated with the device yet.

On Arrival at Your Location

When the devices arrive at your location you can optionally perform a validation procedure by scanning the barcodes on the boxes and calling into our API to do a lookup on the IMEI of each device. This will allow you to validate the device is configured in our platform and can be activated when you are ready. No events are generated as part of this process, since there is still no Event Collector for the device yet.

Ready to Ship to a Customer (Device Provisioning)

When your customer places an order you are ready to provision the device and activate it so you can ship it to your customer in a ready-to-use state. If you would like to modify the device record to store your own identifier for the device, you can make an update request to our API to modify the unique device name to something that has meaning in your system, but this is not a requirement.

Once you have selected the device, you can use the IMEI (or Device Name) from the device to call our API and activate the device.

The first thing we do is create the Event Collector associated with the device so that we have somewhere to store the events for the device. We then look up your device's configuration and call the correct carrier's API to begin the activation process. Depending on the carrier this process can take several minutes, so the result of your request is published as an event to the device. While this process is in progress, the device's status is changed to activating and no other activation commands can be performed on the device until this request finishes.

If everything went as planned, the device is placed in an active state and the msisdn (caller id) for the device is recorded in the device's record (and the Activation event) so you can update your own records with the phone number assigned by the carrier to the device.

The device is now activated on the network and waiting to be turned on once it arrives at the customer.

Arrives at Customer (Customer Activation)

When the device arrives at the customer it comes with instructions in the box to plug in the charger and place the device in the charger in order to complete the activation process. When the device powers up it will attempt to use its SIM card to attach to the carrier network and then send an SMS message to our platform to receive its network configuration. Once it receives its configuration, it will then communicate with our platform to make sure it has been provisioned (in an active state) and determine what software OTA package (OTA == over-the-air) it should begin downloading.

At this point, the device will publish its first On event to the platform to record that it has turned on and that it has communicated successfully with the platform. The device will then download the OTA package, install it, and reboot. As it boots up, the device will again publish an On event (it will do this every time it is powered on) that contains the version number of the software loaded on the device as well as other conditional parameters to help us support the devices.

The platform will give the device all of its configuration settings as part of the bootup process so that the device knows what phone number(s) to call, volume levels, and other settings that determine its operating behavior. It checks to see if firstTimeAudioPlayed setting has been set to determine if this is the first time the user has powered on the device. If this flag has not been set, it will begin the first time activation process for the user and instruct them to push the call button so they can contact the call center for the first time. At this point, the device will also set the flag to true so that this process will be marked complete.

First Time Call

If this is the first time and the user presses the button on the device to place a call, the device will initiate a voice call and simultaneously create a call event on the platform. The event is published as a Normal event. While the call is open, the device continues to send in real time data related to the movement of the device (accelerometer data) and the location data. The event is continuously updated with this information and you will receive periodic updates as the information changes. When the call is closed, you will receive a final update to the event with a Closed state.

The device is now ready for normal use.

In and out of the Charger

It is very important that your customers try to follow a regular charging cycle to give them the best overall peformance of their device, and to insure it is always ready and available in an emergency.

The device publishes an event everytime it is placed in or taken out of the charger (ChargeState event). These events can be used to keep track of how long your customer's are typically charging their devices and/or wearing them.

When the Libris is out of the charger, it may generate events related to location and network status that are stored for later transmission. Other events, such as placing calls, fall detection, and inactivity will be transmitted as soon as they are generated.

When the Libris is placed in the charger, it will immediately transmit any events that were generated and stored while it was outside of the charger. It is important to note that when this happens, you may get a flood of events in your event receiver for all the activities that took place while the Libris was worn outside of the charger.

While the Libris continues to charge, it will turn off its cellular radio for periods of time, intermittenly waking up to communicate with the platform to see if it needs to do anything (place a call, update configuration, install an OTA package) and then going back to sleep.

There are times where the Libris may reboot to reset the radios in order to improve charging efficiency, at which point you will see several events published (Status, On, ChargeState) letting you know this condition occurred. These are all normal events used to let you know how the device is performing in the charger and can help you diagnose devices that are being worn in weak to limited coverage areas.

Fall Detection

If fall detection is enabled, the device continually monitors movement to determine if there is significant activity that might require classification as a fall. If this occurs, the device creates a Classify event on the platform and begins uploading data related to the movement. The platform then classifies the movement as a fall or as active-daily-living (ADL). You will receive the result of Classify events so that you can track when these are occurring in your own device populations.

If the activity was classified as a fall, the device will place a voice call and also open up a data connection as a Fall event. Your platform will receive the fall event information, and periodic updates to the event giving you updated location information. For both fall events and regular call events, you can also choose to open up a real-time connection to our platform to receive the "live" stream from the device, which would give you access to the current accelerometer stream and real-time location updates.

Location Updates

The default device configuration specifies that your device should attempt to obtain a satellite location every 10 minutes. If one is not available, it will try again in another ten minutes. Once a location is received, a LocationFix event is generated and queued up for transmission. Once a certain number of fixes have been generated (default is 12), they will be transmitted to the platform and then to your event receiver. If the device is placed in the charger, all queued up events will be transmitted immediately.

Once in the charger, the device will attempt to get one more location fix, once it is obtained all location fixing is turned off (since the device is in the charger and it already knows where it is). If it received an "in-charger" fix, when the device is removed from the charger it will generate a new fix with a new timestamp using the location it had already received and save that for later transmission.

There are other event types which may contain location data (Normal, Fall) separate from a LocationFix. These ones will typically contain an address that has been translated by Google in addition to the latitude and longitude.

Emergency Call

If the user presses the call button on the Libris device, the device will place a voice call and initiate a data connection to the platform. The platform will generate a Normal event and begin publishing updates for this event. As the call continues, the device will transmit real-time accelerometer data and location updates. You can receive the periodic updates to the event or subscribe to the real-time feed to receive the real-time data.

Returning a Device

If a device is returned there are 2 ways you can handle it depending on what you intend to do with the returned device:

• Deactivate and Return to Inventory
• Reset for a quick turnaround

Deactivation

If you want to deactivate (so the device does not continue to generate billing charges) the device, you can use our platform or API to deactivate the device. This will change the status of the device to "deactivating" while we contact the carrier. Once the carrier process is complete, the device status will change to "deactivated" and we will generate and publish a Deactivation event with the results.

When you are ready to deploy this device to a new patient, you will need to go through a normal activation process as if this was a new device.

Resetting

If you know you will be quickly re-deploying a returned device, it can be more economical to not go through the deactivation/activation process since you can save on the activation charges from the carrier. Using this method you can set the device aside until you are ready to deploy it.

Once you are ready to deploy it, you can perform a reset function (very similar to an activation) using our API or platform to assign the device to a new event collector (patient) and reset all the configuration settings so that the device will behave as if it is brand new for the customer once they receive it. This reset function finishes immediately and returns to the caller immediately, while publishing a Status event for the device letting you know it has been reset.

Integration Use Cases

We provide several methods for integrating with and interacting with the platform, allowing your organization to start quickly by using our provided applications while you plan and implement a tighter integration using our APIs for the future. Below we cover some of the more common scenarios, but it is really up to your organization to determine which pieces of our platform make the most sense for you to use.

Fully Numera-hosted Solution (swivel chair)

When starting out, most organizations choose to use the Numera provided web applications to manage their devices, provision them, and handle inbound calls in the call center. This requires know integration help from your IT department and allows you to evaluate and start deploying Libris devices as quickly as possible.

The only integration that may come into play with this approach is related to the authentication method used for your call-center agents. You can either create accounts for each agent in our platform, or use a shared account for all your agents. Some organizations already have a single-sign-on (SSO) platform in place, in which point we can integrate with your authentication platform so that your agents will not have to sign in separately to our platform. We refer to our security platform as Numera Identity Services (NIS) and this is the component you would integrate with.

Hybrid model

In the hybrid approach, customers typically interface with our APIs to handle all the device management and provisioning while implementing an event receiver to receive all the events. But for active call handling, they use our active-call-page for their agents to handle the alarm. This is typically handled by a URL being transmitted to the event receiver as part of the event for the call, or using a masked URL in your call center application that tells our platform which call you would like to answer.

With this approach you still have to decide how you want your call-center agents to authenticate with our platform. But we offer additional options for the active-call page. We can configure your event receiver to receive a time sensitive url that will expire after a period of time, which does not require the agent to authenticate. And we also offer a masking approach you can implement in your own application to accomplish the same thing. Of course, integrating with NIS is still a viable option.

Fully integrated Solution

For customers with more development oriented capabilities, you can re-create all of the features offered by our web platform and active call pages by using our APIs to create your own custom solution. Our server-server APIs offer all of the features of our platform, while our client-server APIs allow you to quickly develop web based solutions without having to worry about the server-server interactions. We can supply you with a completely functioning active call page using our API that you can use as a starting point for your own development.

This option provides you with the most complete implementation but requires more effort on your part to complete.

Where to go Next

Now that you have a basic understanding of the platform, it is time to learn about our API and how you can use it in your own solutions.

• API Overview