Essentials
flespi entities have customizable fields called metadata. It can be used to store any associated info:
- identifier in some external system
- device-related info, e.g. car license plate or VIN, last service time, etc.
- project comments: e.g., the purpose of a plugin or a calculator, details about a stream destination, etc.
The data may be of any type: string, number, boolean, object, or array.
Maximum textual size of metadata JSON is 64KB and you can define up to 256 root-level keys in it.
How to assign metadata
UI: The last element in any entity Edit tab is a customizable set of metadata fields:
API: Check the "_>" button to see the request curl or explore documentation.
Usage examples
Metadata fields can be used to filter certain instances. For example, a request to find devices that have the numeric field 'fleet_id' equal to 10, or a request to retrieve devices with the string field 'project' containing the substring 'important'.
Parsing with the PVM plugin may rely on metadata fields (more details in this changelog post). For instance, this PVM code will convert the 'position.speed' parameter from kilometers per hour to miles per hour and 'vehicle.mileage' from kilometers to miles based on the string 'units' field:
if optional metadata["units"] == "imperial":optional .vehicle.mileage ==> this * 1.6093 ==> #vehicle.mileageoptional .position.speed ==> this * 1.6093 ==> #position.speed
You can also use metadata("units") function in all expressions in all plugins. For example to pass to the plugin only messages from devices which units are imperial use validate_message='metadata("units") == "imperial"'.
Metadata can be used in flespi analytics. For example you can store per device speed limit in each device's metadata and access this value in analytics counters and selectors using metadata("name") function.
In expressions when you need to access a sub-field inside nested JSON objects in metadata use JSON path to specify it: metadata("/field/subfield").