Units
Depending on the specified flags, the response format may vary.
This chapter describes the flags that can be applied to units and the corresponding parts of the resulting JSON they control. If multiple flags are specified, their respective parts are combined into a single JSON.
Specify flags in DEC format, as described in Data format.
The contents of the response also depend on your access rights to the item. For details, see Flags and access rights.
Unit flags
The following flags may be applied to units:
| HEX value | DEC value | Description |
|---|---|---|
| 0x00000001 | 1 | General properties (base flag) |
| 0x00000002 | 2 | Custom properties |
| 0x00000004 | 4 | Billing information |
| 0x00000008 | 8 | General custom fields |
| 0x00000010 | 16 | Image |
| 0x00000020 | 32 | Messages (subscription only) |
| 0x00000040 | 64 | GUID |
| 0x00000080 | 128 | Administrative custom fields |
| 0x00000100 | 256 | Advanced properties |
| 0x00000200 | 512 | Commands available at the moment |
| 0x00000400 | 1024 | Last message and location |
| 0x00000800 | 2048 | Driver code (outdated) |
| 0x00001000 | 4096 | Sensors |
| 0x00002000 | 8192 | Counters |
| 0x00004000 | 16384 | Routes (outdated) |
| 0x00008000 | 32768 | Maintenance |
| 0x00010000 | 65536 | Unit logs (outdated) |
| 0x00020000 | 131072 | Unit configuration in reports: trip detector and fuel consumption |
| 0x00040000 | 262144 | All other unit settings: message validity filtering (outdated). To get the filter settings, use unit/get_messages_filter. |
| 0x00080000 | 524288 | List of all possible commands for this unit |
| 0x00100000 | 1048576 | Message parameters |
| 0x00200000 | 2097152 | Unit connection status |
| 0x00400000 | 4194304 | Location |
| 0x00800000 | 8388608 | Profile properties |
| 0x01000000 | 16777216 | Tasks (subscription only) |
| 0x3FFFFFFFFFFFFFFF | 4611686018427387903 | Set all possible unit flags. Pass the value as a string or use -1. |
General properties
The flag of general properties is 0x00000001 (1).
{
"mu": <uint>, // Measurement system: 0 — SI, 1 — US, 2 — imperial, 3 — metric with gallons
"nm": "<text>", // Name
"cls": <uint>, // Superclass ID of avl_unit, usually 2 (see the classes key in the token/login response)
"id": <uint>, // Unit ID
"uacl": <long> // User's access rights to this unit (64-bit value)
}
Custom properties
The flag of custom properties is 0x00000002 (2).
The prp object contains custom properties that the Wialon interface and applications store for the unit, so the set of keys varies. The most common keys are listed below.
{
"prp": { // Custom properties
"img_rot": "<text>", // Rotate images: 1 — yes, 0 — no
"label_color": "<text>", // Unit label color: RGB value as a decimal number
"monitoring_sensor_id": "<text>", // Sensor ID which will be displayed in the monitoring system
"motion_state_sensor_id": "<text>", // ID of the sensor used as a motion state source
"sensors_colors_id": "<text>", // ID of the sensor used as a track color source
"use_sensor_color": "<text>", // Use sensor color in the monitoring system: 1 — yes, 0 — no
// One of the parameters for selecting the track color source is used
"sensors_colors": "<text>", // Table of colors for tracks colored based on sensor values
"solid_colors": "<text>", // Solid track color
"speed_colors": "<text>", // Table of colors for coloring tracks based on speed
// Storage of last used colors
"track_sensor": "<text>", // Table of colors for tracks colored based on sensor values
"track_solid": "<text>", // Solid track color
"track_speed": "<text>", // Table of colors for coloring tracks based on speed
"monitoring_battery_id": "<text>" // ID of the sensor showing battery status
},
"ftp": { // FTP settings (used only for accounts)
"hs": "<text>", // Host (only if set)
"lg": "<text>", // Login (only if set)
"pt": "<text>", // Directory path (only if set)
"ch": <uint>, // FTP settings validity: 1 — yes, 0 — no
"tp": <uint>, // Use Wialon hosting FTP: 1 — yes, 0 — no
"fl": <uint> // Wialon hosting FTP availability: 1 — yes, 0 — no
},
"ct": <uint> // Creation time
}
Unit label color
The label_color custom property stores the value of the Unit caption color option. The color is applied either to the caption text or to its background, depending on the Use unit caption color for user setting.
The color is stored as a decimal number converted from the hexadecimal RGB code. For example, red (#FF0000) is stored as "16711680", and light blue (#42AAFF) as "4369151". Don’t pass hexadecimal strings such as "#42AAFF": the server saves the value without validation, but the color is read as a decimal number.
To change the label color, use the item/update_custom_property method:
https://hst-api.wialon.com/wialon/ajax.html?svc=item/update_custom_property¶ms={"itemId":24568421,"name":"label_color","value":"4369151"}&sid=SESSION_IDENTIFIER
Billing information
The flag of billing information is 0x00000004 (4).
{
"crt": <uint>, // Creator ID
"bact": <uint> // Account ID
}
Custom fields
The flag of custom fields is 0x00000008 (8).
{
"flds": { // Custom fields
<text>: { // Custom field ID
"id": <uint>, // ID
"n": <text>, // Name
"v": <text>, // Value
"ct": <uint>, // Creation time (Unix timestamp)
"mt": <uint> // Last modification time (Unix timestamp)
},
...
},
"fldsmax":<long> // Maximum number of custom fields allowed by the billing plan for the account (-1 for unlimited). It can be 0 if the service isn't in the billing plan; existing custom fields are still returned
}
Unit image
The flag of the unit image is 0x00000010 (16).
{
"uri": "<text>", // Path to the unit image on the server. Add it to the Wialon server address to get the image
"ugi": <uint> // Number of image changes
}
Messages
The flag of messages is 0x00000020 (32).
This flag doesn’t add any data to the response. It subscribes the session to new messages of the unit.
To use it, set the flag for the unit with core/update_data_flags. After that, every new message registered for the unit is delivered as an event in avl_evts. The message format depends on the message type and is described on the messages page.
It is recommended to combine this flag with the general properties flag 0x00000001 (1). On its own, the flag of messages makes core/update_data_flags return an empty d object, which looks as if the subscription failed.
To get the last known message of a unit, use the Last message and location flag 0x00000400 (1024). To get messages for a time period, use the messages/load_interval method.
GUID
The flag of GUID is 0x00000040 (64).
{
"gd": "<text>" // Unit GUID
}
Administrative fields
The flag of administrative fields is 0x00000080 (128).
{
"aflds": { // Administrative fields
"<text>": { // Administrative field ID
"id": <uint>, // ID
"n": "<text>", // Name
"v": "<text>", // Value
"ct": <uint>, // Creation time (Unix timestamp)
"mt": <uint> // Last modification time (Unix timestamp)
}
},
"afldsmax": <long> // Maximum number of administrative fields allowed by the billing plan for the account (-1 for unlimited). It can be 0 if the service isn't in the billing plan; existing administrative fields are still returned
}
Advanced properties
The flag of advanced properties is 0x00000100 (256).
{
"uid": "<text>", // Unique ID (hardware)
"uid2": "<text>", // Second unique ID (hardware)
"hw": <long>, // Hardware type
"ph": "<text>", // Phone number
"ph2": "<text>", // Second phone number
"psw": "<text>", // Password
"act": <uint>, // Unit state: 1 — active, 0 — deactivated
"act_reason": <uint>, // Reason for the deactivation
"dactt": <uint>, // Deactivation time
"act_code": <text>, // Activation code. An empty string if the unit has no code
"act_code_tme": <uint>, // Expiration time of the activation code. 0 if the unit has no code
"vp": {...}, // Video billing state. null if video billing isn't set
"retr": {...}, // Retranslation properties. null if they aren't set
"hch": {...} // Health check settings
}
The keys of this flag require different access rights:
| Keys | Access right |
|---|---|
uid, uid2, hw, ph, ph2, psw |
View connectivity settings |
act, act_reason, dactt, act_code_tme, retr, hch |
View object and its basic properties |
vp |
View detailed object properties |
act_code |
Manage activation codes |
To activate or deactivate a unit, use unit/set_active.
The activation code is described on the unit/get_billing_code page, where act_code corresponds to guid and act_code_tme corresponds to tme. The contents of the retr and hch objects are described on the unit/update_retranslation_property and unit/update_health_check pages.
In Wialon Local, the hch key is available starting from version 2504.
The vp object has the following format:
{
"packets": <int>, // Number of purchased traffic packages
"bytes_in": <long>, // Used video traffic, in bytes
"bytes_limit": <long>, // Video traffic limit, in bytes
"hdd_used": <long>, // Used storage space
"hdd_limit": <long>, // Storage space limit
"autopay": <int>, // Maximum number of packages purchased automatically for each month (-1 for unlimited, 0 if disabled)
"status_flags": <int>, // Video billing status flags
"available_traffic": <long>, // Remaining video traffic, in bytes (-1 for unlimited)
"status_ch_ts": <long>, // Time of the last status change (Unix timestamp)
"updated_at": <long> // Time of the last update (Unix timestamp)
}
To manage video billing, use the unit/update_video_status, unit/add_video_packets, and unit/update_video_autopay methods.
Available commands
The flag of available commands is 0x00000200 (512).
{
"cmds": [ // Array of commands
{
"n": "<text>", // Name
"a": <long>, // Access level (access rights the user must have to execute this command)
"t": "<text>", // Link types available for the command, comma-separated: tcp, udp, gsm, vrt
"c": "<text>", // Command type
"p": "<text>", // Parameters. Empty if they aren't set
"jp": "<text>" // JSON parameters as text. Empty if they aren't set
}
]
}
The cmds array contains only the command definitions that the device can execute at the moment. The communication server reports which command types the device currently accepts over each link type (tcp, udp, gsm, vrt). A command definition is excluded if its command type isn’t available over any link type. It’s also excluded if a specific link type is set in the definition and the command type isn’t available over that link type. The t field lists all link types over which the command type is currently available, even if the definition has a specific link type. For example, for a definition with the automatic link type (empty l value), t can be tcp,vrt. To get all command definitions of the unit, use the unit/get_command_definition_data method.
The types of commands and links, as well as the p and jp parameters, are described on the unit/update_command_definition page. The available command types depend on the device type. The list of access flags for units is provided in the General and Units and unit groups sections on the core/check_items_billing page.
Last message and location
The flag of the last message and location is 0x00000400 (1024).
{
"pos": { // Last known location. null if the unit has no messages with a location
"t": <uint>, // Time (UTC)
"f": <uint>, // Flags of the message with this location
"lc": <int>, // LBS message checksum
"y": <double>, // Latitude
"x": <double>, // Longitude
"z": <double>, // Altitude
"s": <int>, // Speed
"c": <int>, // Course
"sc": <int> // Number of satellites
},
"lmsg": { // Last known message. null if the unit has no messages
...
}
}
The possible values of the f field are listed in the data message section.
The y, x, and c fields are missing if the location comes from a message registered during a private trip, that is, if the f field contains the flag 0x40000 (262144). This happens when the unit has a private mode sensor with the Do not show unit location option enabled. In this case, the fields aren’t set to zero; they’re absent from the pos object.
The message format depends on the message type. All types are described on the messages page.
Sensors
The flag of sensors is 0x00001000 (4096).
{
"sens": { // Sensors
"<text>": { // Sensor ID
"id": <long>, // ID
"n": "<text>", // Name
"t": "<text>", // Type
"d": "<text>", // Description
"m": "<text>", // Unit of measurement
"p": "<text>", // Parameter
"f": <uint>, // Sensor flags
"c": "<text>", // Configuration
"vt": <uint>, // Validation type
"vs": <long>, // Validation sensor ID
"tbl": [ // Calculation table
{ // Parameters
"x": <double>,
"a": <double>,
"b": <double>
}
],
"ct": <uint>, // Creation time (Unix timestamp)
"mt": <uint> // Last modification time (Unix timestamp)
},
...
},
"sens_max": <long> // Maximum number of sensors allowed by the billing plan for the account (-1 for unlimited). It can be 0 if the service isn't in the billing plan; existing sensors are still returned
}
In Wialon Local, the ct and mt fields of sensors are available starting from version 2304.
Sensor flags, types of sensors and validation, as well as examples of configuration are provided on the unit/update_sensor page.
Counters
The flag of counters is 0x00002000 (8192).
{
"cfl": <uint>, // Calculation flags
"cnm": <uint>, // Mileage counter, km or miles depending on the measurement system of the unit
"cnm_km": <uint>, // Mileage counter, always in km
"cneh": <double>, // Engine hours counter, h
"cnkb": <uint> // GPRS traffic counter, KB
}
The cnm counter is converted to miles if the measurement system of the unit is US or imperial. The cnm_km counter holds the same value, but always in km. The measurement system is stored in the mu field of the general properties.
Calculation flags are described on the unit/update_calc_flags page.
Maintenance
The flag of service intervals is 0x00008000 (32768).
{
"si": { // Service intervals
"<text>": { // Service interval ID
"id": <uint>, // ID
"n": "<text>", // Name
"t": "<text>", // Description
"im": <uint>, // Mileage interval
"it": <uint>, // Days interval
"ie": <uint>, // Engine hours interval
"pm": <uint>, // Last service for mileage interval, km
"pt": <uint>, // Last service for days interval, sec (UTC)
"pe": <uint>, // Last service for engine hours interval, h
"c": <uint>, // Done times
"ct": <uint>, // Creation time (Unix timestamp)
"mt": <uint> // Last modification time (Unix timestamp)
},
...
},
"simax": <long> // Maximum number of service intervals allowed by the billing plan for the account (-1 for unlimited). It can be 0 if the service isn't in the billing plan; existing service intervals are still returned
}
Trip detector and fuel consumption
The flag of the trip detector and fuel consumption is 0x00020000 (131072).
{
"rtd": { // Trip detector
"type": <uint>, // Type of movement detection
"gpsCorrection": <int>, // Allow GPS correction: 0 — no, 1 — yes
"minSat": <uint>, // Minimum number of satellites
"minMovingSpeed": <uint>, // Minimum moving speed, km/h
"minStayTime": <uint>, // Minimum parking time, seconds
"maxMessagesDistance": <uint>, // Maximum distance between messages, meters
"minTripTime": <uint>, // Minimum trip time, seconds
"minTripDistance": <uint> // Minimum trip distance, meters
},
"rfc": { // Fuel consumption
"calcTypes": <uint>, // Type of calculation
"fuelLevelParams": { // Detection of fuel fillings and thefts
"flags": <uint>, // Flags of fillings and thefts
"ignoreStayTimeout": <uint>, // Ignore messages after the start of motion, s
"minFillingVolume": <double>, // Minimum fuel filling volume, liters
"minTheftTimeout": <uint>, // Minimum stay timeout to detect fuel theft, s
"minTheftVolume": <double>, // Minimum fuel theft volume, liters
"filterQuality": <ubyte>, // Filtering level (0..255)
"fillingsJoinInterval": <uint>, // Timeout to separate consecutive fillings, s
"theftsJoinInterval": <uint>, // Timeout to separate consecutive thefts, s
"extraFillingTimeout": <uint> // Timeout to detect final filling volume, s
},
"fuelConsMath": { // Consumption math
"idling": <double>, // Idling, liters per hour
"urban": <double>, // Urban cycle, liters per 100 km
"suburban": <double> // Suburban cycle, liters per 100 km
},
"fuelConsRates": { // Consumption by rates
"consSummer": <double>, // Summer consumption, liters per 100 km
"consWinter": <double>, // Winter consumption, liters per 100 km
"winterMonthFrom": <int>, // Winter from (month: 0-11)
"winterDayFrom": <int>, // Winter from (day 1-31)
"winterMonthTo": <int>, // Winter to (month 0-11)
"winterDayTo": <int> // Winter to (day 1-31)
},
"fuelConsImpulse": { // Impulse fuel consumption sensors
"maxImpulses": <int>, // Maximum number of impulses
"skipZero": <int> // Skip the first zero value
}
}
}
Types of movement detection are described on the unit/get_trip_detector page. Types of fuel consumption calculation as well as filling and theft flags are described on the unit/get_fuel_settings page.
Commands
The flag of commands is 0x00080000 (524288).
{
"cml": { // List of commands
"<text>": { // Command ID
"id": <uint>, // ID
"n": "<text>", // Name
"c": "<text>", // Type
"l": "<text>", // Link type
"p": "<text>", // Parameters
"a": <long>, // Access level (access rights the user must have to send this command)
"f": <uint>, // Phone number flags: 0 — any (primary, then secondary), 0x1 — primary, 0x2 — secondary
"jp": "<text>",// JSON parameters (only if set)
"ct": <uint>, // Creation time (Unix timestamp)
"mt": <uint> // Last modification time (Unix timestamp)
},
...
},
"cml_max": <long> // Maximum number of commands allowed by the billing plan for the account (-1 for unlimited). It can be 0 if the service isn't in the billing plan; existing commands are still returned
}
The types of commands and links are described on the unit/update_command_definition page. The available command types depend on the device type. The list of access flags for units is provided in the General and Units and unit groups sections on the core/check_items_billing page.
Message parameters
Allows using the accumulative system of message parameter values. Parameters will be stored in the corresponding JSON object section, which will store not only the values of parameters from the last message, but also the values of parameters from earlier messages.
The flag of message parameters is 0x00100000 (1048576).
{
"prms": { // List of message parameters
"<text>": { // Parameter name
"v": <any>, // Parameter value: a number, a string, or an object
"ct": <uint>, // Time of the last value change
"at": <uint> // Time of the last message with this parameter
},
...
}
}
The prms key is missing if the unit hasn’t sent any messages. If the session has a limit on the number of parameters, the response contains an empty prms object and "prms_total": 0 instead (see Limited list of parameters).
When the unit sends a new message, the session receives an event with the parameters of this message in the prms object. If the value of a parameter hasn’t changed, the event contains only the time of the message instead of the full object:
{
"prms": {
"<text>": <uint> // Parameter name: time of the last message with this parameter
}
}
Limited list of parameters
For units with a large number of parameters, for example, units with BLE tags, the full list can be very large. To get only the most recent parameters, set a limit with core/set_prms_limit before you request the data. The limit applies to all the units of the session.
With a limit, the response contains no more than the specified number of parameters, the ones that came in the latest messages received by the server. The prms_total field contains the total number of the unit parameters:
{
"prms": { // Most recent message parameters
"<text>": { // Parameter name
"v": <any>, // Parameter value: a number, a string, or an object
"ct": <uint>, // Time of the last value change
"at": <uint> // Time of the last message with this parameter
},
...
},
"prms_total": <uint> // Total number of message parameters of the unit
}
The limit changes the behavior of the session as follows:
- Each core/update_data_flags request with the flag of message parameters in mode 1 returns the current list of the most recent parameters, even if the unit already has this flag in the session.
- Events contain all the parameters of the new message, not only the ones returned earlier, and the number of these parameters isn’t limited. Each parameter is always returned as a full object with the
v,ct, andatfields. - The session doesn’t receive the full list of parameters when the server rebuilds it. To get the current list, repeat the
core/update_data_flagsrequest.
The limit applies only to the prms object. Other unit properties, for example, the parameters of the last message, are returned in full.
The core/set_prms_limit method isn’t available in Wialon Local.
Connection
The flag of the unit connection status is 0x00200000 (2097152).
{
"netconn": <int> // Connection status: 1 if the unit has an active TCP or UDP connection, 0 if it doesn't
}
Location
The flag of the unit location is 0x00400000 (4194304).
{
"pos": { // Last known location. null if the unit has no messages with a location
"t": <uint>, // Time (UTC)
"f": <uint>, // Flags of the message with this location
"lc": <int>, // LBS message checksum
"y": <double>, // Latitude
"x": <double>, // Longitude
"z": <double>, // Altitude
"s": <int>, // Speed
"c": <int>, // Course
"sc": <int> // Number of satellites
}
}
The possible values of the f field are listed in the data message section.
The y, x, and c fields are missing if the location comes from a message registered during a private trip, that is, if the f field contains the flag 0x40000 (262144). This happens when the unit has a private mode sensor with the Do not show unit location option enabled. In this case, the fields aren’t set to zero; they’re absent from the pos object.
Profile properties
The flag of profile properties is 0x00800000 (8388608).
{
"pflds": { // Profile fields
"<text>": { // Profile field ID
"id": <uint>, // ID
"n": "<text>", // Name
"v": "<text>", // Value
"ct": <uint>, // Creation time (Unix timestamp)
"mt": <uint> // Last modification time (Unix timestamp)
},
...
},
"pfldsmax": <long> // Maximum number of profile fields allowed by the billing plan for the account (-1 for unlimited). It can be 0 if the service isn't in the billing plan; existing profile fields are still returned
}
Tasks
The flag of tasks is 0x01000000 (16777216).
In Wialon Local, this flag is available starting from version 2504.
This flag doesn’t add any data to the response. It subscribes the session to new task messages of the unit.
To use it, set the flag for the unit with core/update_data_flags. After that, every new task message registered for the unit is delivered as an event in avl_evts in the following format:
{
"i": <long>, // Unit ID
"t": "m", // Event type: new message
"d": {
"t": <int>, // Message time
"f": <int>, // Message flags
"tp": "task", // Message type
"task_id": <text>, // Task ID
"p": {} // Task fields
}
}
The p object holds the fields of the task: its status, priority, assignee, comments, and others. These are the same fields that messages/get_task_messages returns.
A task is also delivered as a new event every time it’s changed, for example, when its status is updated or a comment is added. Such an event has the same task_id as the original task, and its message time t is still the time when the task was created. The time of the change is in the task_update_time parameter. To keep the current state of a task, replace the stored task that has the same task_id with the one from the latest event.
To receive task events, you need the Request reports and messages access right to the unit. For the other unit events, the View object and its basic properties access right is enough. The Tasks service must also be enabled and active for the account.
It is recommended to combine this flag with the general properties flag 0x00000001 (1). On its own, the flag of tasks makes core/update_data_flags return an empty d object, which looks as if the subscription failed.
To get the task messages of a unit for a time period, use the messages/get_task_messages method. To edit a task, use unit/update_task.