Messaging & Notification

Libre Application Tasks can send notification messages to users.

Notification messages will show up on recipients’ Smartphone.

Types of Notification Messages

There are two types of messages, State Message and Persistent Message.

  • State Message - State message will not be persisted. If the Hub reboots, the state messages will be either regenerated or lost.
  • Persistent Message - Every persistent message will be saved into flash memory of the Liberty IoT Hub. The messages will survive between reboots.

Severity Level

There are 7 levels represents the severity of a message:

  • 1- Alert_1 Debug
  • 2- Alert_2 Info
  • 3- Alert_3 AlertLow (Green alert)
  • 4- Alert_4 AlertGuarded (Blue alert)
  • 5- Alert_5 AlertElevated (Yellow alert)
  • 6- Alert_6 AlertHigh (Orange alert)
  • 7- Alert_7 AlertSevere (Red alert)

Message Sender

A message always has a sender. It could be a device, a user, or some object of other types.

For messages sent from an App Task, the Task is always the sender.

Message Source

A message always has a source. For messages sent from an App Task, by default, the source is the Task itself. Nevertheless, the source may be another object which the Task has access to.

For example, a Task may constantly track the battery level of a wireless device, if the Task determines that the battery level is low, is may send an alert message to a user (or a list of users) to remind them to replace the battery. In this case, the message source could be the device the Task is monitoring.

State Message ID

If a message is a state message, it shall have a state ID. The state ID is an integer ranging between 1 and 65535.

The state ID is decided by App developer. If Task sends to messages with the same state ID, the state is said to be “updated”. The recipients will receive the message with updated state.

The state identified by state ID can also be programmatically cleared.

Message Recipients

A message shall have a list of recipients. Recipients is a list of user ID or group ID. Note if group ID is included then every user defined in the group (include child groups) will be notified.

Application developer most likely won’t care about recipients because it is simply an array of users that requires user input when creating Task.

Message Text and Language Localization

Liberty-IoT-OS design provides comprehensive support of text localization of message texts.

Instead of sending literal strings with message, Task can send a message with a “String Resource Name”.

The list of string resources can be translated into any language.

The string resource can be a string used to format the actual string with a list of variables. The variables are also supplied by Task during runtime. We use the IEEE printf string format that is compatible with Android, iOS and C/C++.

Further more, the “printf” variables can also has a “Resource String Name” that refer to a localized string in string resource.

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

Messaging API

Libre_MessageText(level, source, recipients, resource_name, …)

Send out a persistent message.

Libre_MessageStateText(stateId, level, source, recipients, resource_name, …)

Send out a state message.

Libre_MessageStateClear(stateId, level, source, recipients)

Clear the state of the specified source.

Parameters:

  • stateId - Only applies to state messages. It ranges between 1 and 65535. The value is decided by App developers
  • level - Level of the message, see “Severity Level” for details, note level ranges between 1 and 7
  • source - A Lua table object representing the message source; or “nil” (default to task itself)
    • type - A string representing source type
      • “device”, a physical device
      • “logical”, a logical device
      • “user”, a user or group
    • id - The object Id (a number)
  • recipients - A list of users or groups that will receive the messages
  • resource_name - The name of the string resource that represents the actual text string. Note the resource string may be a format template following IEEE printf standard, see “String Resources” for more details.
  • [ … ] - If resource_name represents a formatting template, a list of values will be supplied as extra arguments. The variables shall be a of type of “boolean”, “number” and “string”, or a table object that represents special variables

Special Variables

The variable may be of special string or number types. Special variables are “Lua table” objects, with the following structure:

Special String

Special string represents a string resource referenced by name.

  • type - “string”
  • name - The resource name

Special Number

Special number represents a number of specified “Units of Measure”. The special number is used in scenarios that involve flexible uint conversion based on localization of client (Smartphone). 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 inchs, feet, or yards, or kilograms vs pounds or ounces).

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

Special Liberty IoT Hub Object

Liberty IoT Hub Objects may be of following types:

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

Those objects can be renamed on smartphone client, for localization or any other purposes. The rendering of these objects could be simply the string representing the name of the object. In the future, more versatile rendering may be implemented.

  • type - “libre-obj”
  • obj-type - Integer with valid values below:
    • 0 - “device”
    • 1 - “logical-device”
    • 4 - “user”
  • value - The object ID, as an integer

Note: If there is one Liberty IoT Hub Object involved, it shall be made “source” of the message. This type shall only be used if there are more than one objects involved in the message, which is very rare! The App’s use of these objects will be subject to runtime security access check of the Task.

Example

The example below sends notification message with today’s weekday string.

function SampleSendSpecialStringWeekday(recipients)
    local date = os.date("*t")
    -- wday is weekday, 1 is Sunday
    Libre_MessageText(2, nil, recipients, "RES_TODAY", {type='string', name=string.format('RES_WEEKDAY%d', date.wday)})
end

The example below sends notification with a random temperature.

function SampleSendSpecialStringTemperature(recipients)
    -- v is a random number ranges between 20 and 30
    local v = math.random() * 10 + 20
    Libre_MessageText(2, nil, recipients, "RES_TEMP", {type='unit', unit='Cel', value=v})
end

Behavior on Android and iOS Devices

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

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

“Liberty-IoT-OS API” column is the level in API.

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

Mobile Client Liberty-IoT-OS API Android iOS
Alert_1 Debug 1- Debug 0- IMPORTANCE_NONE Banner
Alert_2 Information 2- Info 1- IMPORTANCE_MIN Alert no sound
Alert_3 Notification 3- AlertLow (Green alert) 2- IMPORTANCE_LOW Alert no sound
Alert_4 Warning 4- AlertGuarded (Blue alert) 3- IMPORTANCE_DEFAULT Alert with sound
Alert_5 Alert 5- AlertElevated (Yellow alert) 4- IMPORTANCE_HIGH Alert with sound
Alert_6 High Alert 6- AlertHigh (Orange alert) 5- IMPORTANCE_MAX Critical alert
Alert_7 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 notification immediately as long as network connection is good
  3. It’s more secure and offers much better privacy protection
  4. It work on all Anroid devices, even those devices without Google services installed, e.g. Amazon Fire Tablets

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