Messaging & Notification

Libertas Thing-App tasks Tasks can send notification messages to users.

Notification messages will show up on recipients’ smartphones.

Designed for Maximum Independence and Privacy Protection

• On Android, use TCP long poll to eliminate dependency on any third-party messaging service.
• On iOS, notification messages are end-to-end encrypted.

Libertas Hub will save every persistent message into the internal persistent storage. Therefore, the messages will survive between reboots.

Severity Level

There are seven levels of severity of a message:

• 1- Debug
• 2- Info
• 3- AlertLow (Green alert)
• 4- AlertGuarded (Blue alert)
• 5- AlertElevated (Yellow alert)
• 6- AlertHigh (Orange alert)
• 7- AlertSevere (Red alert)

Message Sender

A message always has a sender. It could be a device, a user, or a Thing-App Task.

The Thing-App Task is always the sender of messages sent from a Thing-App Task.

Message Source

A message always has a source. By default, the “source” is the task for messages sent from a Thing-App Task. Nevertheless, the source may be another object to which the task has access.

For example, a Task may constantly track the battery level of a wireless device; if the Thing-App task determines that the battery level is low, it may send an alert message to a user (or a list of users) to remind them to replace the battery. The message source could be the Thing-App task that monitors the device.

Message Recipients

A message shall have a list of recipients. The recipient is a list of user IDs or group IDs. Note if the group ID is included, every user in the group (including child groups) will be notified.

Thing-App developers most likely won’t care about recipients because it is simply an array of users or user groups. Usually, the recipient list shall be part of the configuration argument if a Thing-App. In other words, when a user creates a Thing-App task, the user must add users or user groups to the recipient list as part of the task config data.

String Resource

Libertas-OS design provides comprehensive support for text localization of message texts.

A Thing-App task never sends out a message with literal strings. Instead, it always sends a message with a “String Resource Name.” the corresponding string resource can be translated into other localized languages.

The string resource can format the actual text with a list of variables. The variables are also supplied by the Thing-App task during runtime. We use the IEEE printf string format compatible with Android, iOS, and C/C++.

Furthermore, a “printf” argument can also have a “Resource String Name” that refers to a localized string in string resource.

Read “String Resources” to find out how to manage and translate string resources.

Messaging API

• Libertas_MessageText - Send out a notification message.

function Libertas_MessageText(level: LibertasMessageLevel, source: LibertasMessageSource|undefined, recipients: LibertasUser|LibertasUser[], resource_name: string, ...args: LibertasMessageArgument[]): void

The resource_name is the name of a string resource. The string resource follows the printf format. It may have zero or more additional arguments. Each LibertasMessageArgument could be a number, boolean, string, or a complex LibertasMessageVariable.

declare type LibertasMessageArgument = number|boolean|string|LibertasMessageVariable;

LibertasMessageVariable

One of the message text arguments may be a LibertasMessageVariable.

declare interface LibertasMessageVariable {
    /**
     * Type of variable, could be the following
     * - "string" - {@link LibertasMessageVariableString}
     * - "unit" - {@link LibertasMessageVariableUnit}
     * - "libertas-obj" - {@link LibertasMessageVariableObject}
     */
    type: string;
}

/**
 * Represents a string variable as part of a message sent from Task to end-user's smartphone.
 * 
 * @see [String Resources](/doc/developers_doc/string_resources/)
 */
declare interface LibertasMessageVariableString extends LibertasMessageVariable {
    type: "string";
    /**
     * The name of the resource string.
     */
    name: string;
}

/**
 * Represents a unit variable as part of a message sent from Task to end-user's smartphone.
 * 
 * @remarks
 * The unit may be presented differently based on the end-user's locale information.
 * For example, if the variable is a number with “Unit of Measure” of “degree Celsius”. 
 * It will be automatically converted to “degree Fahrenheit” on users’ smartphones with localization of 
 * “United States”. The same is true for length or weight (meters vs inches, feet, or yards, or kilograms vs pounds or ounces). 
 */
declare interface LibertasMessageVariableUnit extends LibertasMessageVariable {
    type: "unit";
    /**
     * The unit code, defined in [“The Unified Code for Units of Measure”](https://unitsofmeasure.org/ucum) (look for the “c/s” field).
     */
    unit: string;
    /**
     * The unit value.
     */
    value: number;
}

/**
 * Represents an object variable as part of a message sent from Task to end-user's smartphone.
 * 
 * @remarks
 * The object may be of type device, logical-device or user.
 */
declare interface LibertasMessageVariableObject extends LibertasMessageVariable {
    type: "libertas-obj";
    /**
     * The object type.
     */
    "obj-type": LibertasSystemObjectType;
    /**
     * The object ID.
     */
    value: number;
}

LibertasMessageVariableString

LibertasMessageVariableString represents a string resource referenced by name.

• type - “string”
• name - The resource name, see “String Resources” for more details.

LibertasMessageVariableUnit

LibertasMessageVariableUnit represents a number with specified “Units of Measure.” The “special number” is used in scenarios involving flexible uint conversion based on the client’s localization (Smartphone). For example, if the variable is a number with a “Unit of Measure” of “degree Celsius.” It will be automatically converted to “degree Fahrenheit” on users’ smartphones with localization of “United States.” The same applies to length or weight (meters vs. inches, feet, yards, or kilograms vs. pounds or ounces).

• type - “unit”
• unit - The unit code, defined in “The Unified Code for Units of Measure” (look for the “c/s” field).
• value - The value as a number

Note: “Special numbers” are only needed where there is a potential unit conversion, most likely between the United States and the rest of the world. Such numbers are most likely for temperature, length, and weight. For units that do NOT require unit conversion, for example, kWH, using the plain number is enough.

LibertasMessageVariableObject

LibertasMessageVariableObject may be of the following types:

• Physical Devices, such as a WIFI/Ethernet device
• Logical Devices, such as a load object, a scene, etc
• User

Those Libertas-things can be renamed for localization or other purposes on smartphone clients. The rendering of these Libertas-things could be simply the string representing the Libertas-thing’s name. In the future, more versatile rendering may be implemented.

• type - “libre-obj”
• obj-type - A LibertasSystemObjectType
• value - The object ID, as an integer

Note: If one Libertas Hub Object is involved, it shall be made the “source” of the message. This type shall only be used if more Libertas-things are involved in the message, which is rare! The Thing-App’s use of these Libertas-things will be subject to runtime security access checks of the task.

Behavior on Android and iOS Devices

Below is a brief description of the behavior of different notification levels.

The “Mobile Client” column is the display title on the mobile client.

“Libertas-OS API” column is the level in API.

“Android” and “iOS” columns are corresponding behaviors.

Mobile Client	Libertas-OS API	Android	iOS
Debug	1- Debug	0- IMPORTANCE_NONE	Banner
Information	2- Info	1- IMPORTANCE_MIN	Alert no sound
Notification	3- AlertLow (Green alert)	2- IMPORTANCE_LOW	Alert no sound
Warning	4- AlertGuarded (Blue alert)	3- IMPORTANCE_DEFAULT	Alert with sound
Alert	5- AlertElevated (Yellow alert)	4- IMPORTANCE_HIGH	Alert with sound
High Alert	6- AlertHigh (Orange alert)	5- IMPORTANCE_MAX	Critical alert
Severe Alert	7- AlertSevere (Red alert)	5- IMPORTANCE_MAX	Critical alert

Android TCP Long Poll

On Android devices, a foreground service with TCP long-polling is preferred. Here are the reasons:

1. It is pretty battery efficient
2. It is the most responsive. You will get a notification immediately as long as the network connection is good
3. It’s more secure and offers much better privacy protection
4. It works on all Android devices, even those devices without Google services installed, e.g., Amazon Fire Tablets

For more information, please refer to “Smartphone User Manual”.

Example

There is an example in “LibertasTutorial”.