Link Search Menu Expand Document
Libertas Things Documentation

Attributes

The Thing-App UI is a task config data editor.

Task config data is a tree-data following the Thing-App function schema, which is also a tree-data.

On the schema tree, a node may have additional information for further constraints, user interface optimization, or both. This additional information is called “attributes”.

Attributes cannot be defined in the Thing-App source code. Libertas IDE provides a GUI tool for attribute management, the Signature Editor.

Libertas Signature Editor

Developers manage attributes using the “Libertas Signature Editor” GUI tool.

Thing-App Signature Editor

Number Related Attributes

The following attributes apply to the Number type. These attributes will affect client UI input normalization and validation (e.g., Smartphone).

  • Min - A number represents the minimum acceptable value.
  • Max - A number represents the maximum acceptable value.
  • Step - A number constrains the minimum precision. It must be used with “Min,” “Max,” or both.
  • Default - Default value initialized.
  • ShowPercentage - Only valid with “Min,” “Max,” and “Step” are all specified. A percentage indicator (0%-100%) and the value on users’ screens will be displayed.
  • Physical Quantity - The number represents a physical quantity. The physical quantity has the following properties:
    • Quantity Type - Type of physical quantity.
      • Temperature
      • Length
      • Mass
    • Units of Measure - The unit of measure of this value, which is defined in “The Unified Code for Units of Measure” (look for the “c/s” field).
      • Temperature
        • “Cel” - Temperature degree Celsius
        • “[degF]” - Temperature degree Fahrenheit
      • Length
        • “m” - Meter
        • “km” - Kilometer
        • “cm” - Centimeter
        • “mm” - Millimeter
        • “mil” - Mil
        • “[in_i]” - Inch
        • “[ft_i]” - Foot
        • “[yd_i]” - Yard
        • “[mi_i]” - Mile
      • Mass
        • “g” - Gram
        • “kg” - Gram
        • “[gr]” - Grain
        • “[lb_av]” - Pound
        • “[oz_av]” - Ounce

The end-user UI can be optimized based on user attributes. For example, a wheel can be used to facilitate the steps. A percentage value can also be displayed along with the actual value.

For example, the level of lighting is 0-255. A percentage value will give the regular user a better understanding.

Number Editor with Percentage, Step Wheel, and Value Input.

Number Editor

Number Editor with Value Input only.

Number Editor

Display Percentage along with Value

Number Editor

Physical Quantity

A “Physical Quantity” field is required to define a “Target Unit” and a list of “Alternative Lists.”

For example, a “Temperature Field” may be defined as below:

Physical Temperature

“Target Unit” and “Alternative Units” can be further customized:

Physical Temperature Unit

“Target Unit” is used to input the Thing-App code. In the example above,

  • “Target Unit” is in Celsius
  • The value ranges between 7°C and 32°C, with a step of 0.1°.

“Alternative Units” defines a list of units that affect the user interface (on Smartphones). In the example above,

  • Alternative Units defines both Celsius (°C) and Fahrenheit (°F).
  • Note Celsius is defined again with a different step value (precision) of 0.5°C.
  • Fahrenheit defines a range that is close to the range of Celsius (between 45°F and 89°F).

Fahrenheit is now only in the United States and its island territory. The Smartphone will automatically adopt the correct input UI based on the phone’s Regional Settings.

For example, the British and the United States use English. However, the UI will accept Celsius (°C) on the phone with the British region, while on phones with the United States region, Fahrenheit (°F) will be used.

No matter what unit is used in the UI, the user input will be automatically converted into a “Target Unit,” Celsius with 0.1 °C precision (step value).

The screenshots below demonstrate a task with different region settings (the United States and China).

Note the UI is automatically translated, and temperature Units are automatically adjusted.

Eng Cn

Note: Only temperature conversion is supported with the current release. More unit conversion will be implemented in the future.

Default Attribute

  • Default - Default value when first initialized on UI. This attribute can be applied to Number, Boolean, String, and Enumeration types.

Device Related Attributes

A Device must have additional constraints. Signature Editor UI enforces this rule.

Device type constraints can have more than one entry. Entries are “or” ed together.

For example, below represents “On/off Load” or “Level Control Load” devices.

Device Type

Each entry may have more than one “capability” and together.

For example, in the UI below, more “capabilities” can be added along with “On/off”.

Device Type

Other Attributes on Device

  • Custom Access - The device can be read-only or write-only. The flag may affect device binding.
  • Exclusive Write - Only one task is allowed to write (control) the device.

Suppose one task with “Exclusive Write” on a device is started. Only tasks with “Readonly” on the same device are allowed to run.

Virtual Device Related Attribute

A virtual device is forced to have an attribute with the following information.

  • Load Types
  • Device Type
  • Capabilities (1 or more is allowed)

Virtual Device Type

Nullable (Optional) Attribute

If a node has a “Nullable” attribute, the node can be a special “Null.” “Nullable” applies to any type except for List (array) item. In other words, a List can not have an “undefined”/”Null” member item.

The nullable is defined in the source code with “?” modified in Typescript.

In Rust, the nullable is defined in the source code with Option;

The nullable type will be displayed with a “Create” button on the user’s screen.

Nullable create

The user clicks the “Create” button to create a default value for the nullable type, for example, a boolean value.

Nullable create

Users can also “delete” a nullable value. Once deleted, the value will be reset to “null” again.

Nullable create

Header Attribute

Header optimizes the presentation of tree data for table and list types.

On Table Members

A Header attribute on a table member will make the member the “header” of the table in the UI display.

Below is the example from the Light Show demo. If the “light” field has a “Header,” the result is shown on the right side. You can see that the “light” field represents the table of a “lightState”.

Header Table

On a List Member

The “Header” attribute can also be used on a list member. The screenshot below demonstrates that in a presentation of a list (array), “lightStates” replaces “group.”

The “Header” attribute saves space on the screen and makes the UI more intuitive and easier to work with for users.

Header Table

List Related Attributes

  • Minimum Size - Minimum allowed size.
  • Maximum Size - Maximum allowed size.
  • Unordered Set - The member item order is unimportant. This attribute allows UI optimization.

“Unique” Attribute

The attributes below can be applied to certain types (Enumeration, User, Device).

  • Unique - The value has to be unique among other array members.

Combining “Unordered Set” on a List and “Unique” on a member allows powerful UI optimization on the “Enumeration,” “Device,” and “User” types. It will turn a list (array) into a multi-select check dialog.

Nulti Enum Multi Device

Note the beauty of this “Unique” attribute: it doesn’t limit to the direct child of an array. It can be an indirect child deep down the type tree of an array member.

Device Type

Task Related Attributes

  • Singleton - Only one task instance of this function (regardless of which version of Thing-App) can run.

Security Related Attributes

To be supported in the future.

  • URL - External URL access whitelist

Work in Progress

Libertas is a work in progress. New attributes may be introduced in the future.