com.webos.service.uwb

API Summary

Provides UWB (Ultra Wideband) service for wireless connectivity based on IEEE 802.15.4a/z. This service connects to Luna bus to interact with other system components (e.g. apps, services) that require UWB services.

Overview of the API

This service must be used when an application needs to get UWB's positioning information (ex. ranging and angle-of-arrival).

This service provides a group of payload data-specific utilities:

Common - common/generic data for standard protocol
ToBeExtensiable - Other vendor-specific data (if needed)

Methods

getUwbServiceState

ACG: uwb.operation

Description

Retrieves the values for UWB service's state. If subscribe is set to true, then getUwbServiceState sends an update if the values change. This method queries the state of UWB service.

Parameters

Name	Required	Type	Description
subscribe	Optional	Boolean	Subscribe for notifications on changes in the values. Possible values are: true: Subscribed. false: Not subscribed.

Name

Required

Type

Description

Optional

Boolean

Subscribe for notifications on changes in the values.

Possible values are:

true: Subscribed.
false: Not subscribed.

Call Returns

Name	Required	Type	Description
serviceAvailability	Required	Boolean	Indicates the state of UWB service. Possible values are: true: Service is available. false: Service is not available.
stateChangeReason	Optional	String	Indicates the reason why the state has been changed. Possible values are: Unknown: Changed for an unknown reason. SessionStarted: Changed because a session started. AllSessionsClosed: Changed because all sessions were closed. SystemPolicy: Changed because of a device system change. SystemBoot: Used to signal the first adapter state message after boot.
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Operation is successful. false: Operation has failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	The reason for the failure of the operation.
subscribed	Required	Boolean	Indicates if subscribed to get notifications.

Subscription Returns

Name	Required	Type	Description
serviceAvailability	Required	Boolean	Indicates the state of UWB service.
stateChangeReason	Optional	String	Indicates the reason why the state has been changed.
subscribed	Required	Boolean	Indicates if subscribed to get notifications.

Example

Example scenario

# luna-send -f -n 1 luna://com.webos.service.uwb/getUwbServiceState '{}'

Response:

{
"subscribed": false,
"returnValue": true,
"serviceAvailability": false
}

getUwbSpecificInfo

ACG: uwb.operation

Description

Provides the capabilities and features of the device (supported UWB protocols and parameters).

Parameters

Name	Required	Type	Description
subscribe	Optional	Boolean	Subscribe for notifications on changes in the values. Possible values are: true: Subscribed. false: Not subscribed.

Name

Required

Type

Description

Optional

Boolean

Subscribe for notifications on changes in the values.

Possible values are:

true: Subscribed.
false: Not subscribed.

Call Returns

Name	Required	Type	Description
modState	Optional	Boolean	Indicates the state of UWB module. Possible values are: true: Module is normal. false: Module is not normally initiated.
fwVersion	Optional	String	The firmware version of UWB module.
fwCrc	Optional	String	The firmware CRC of UWB module.
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Operation is successful. false: Operation has failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	The reason for the failure of the operation.

Subscription Returns

Name	Required	Type	Description
modState	Optional	Boolean	Indicates the state of UWB module.
fwVersion	Optional	String	The firmware version of UWB module.
fwCrc	Optional	String	The firmware CRC of UWB module.
subscribed	Required	Boolean	Indicates if subscribed to get notifications.
returnValue	Required	Boolean	Indicates the status of the operation.

Example

Example scenario

# luna-send -n 1 -f luna://com.webos.service.uwb/getUwbSpecificInfo '{}'

Response:

{
"subscribed": false,
"returnValue": true,
"fwVersion": "0",
"modState": false,
"fwCrc": "0"
}

getRangingInfo

ACG: uwb.operation

Description

Provides the information of ranging/aoa that are received from the remote UWB devices.

The actual ranging data is an optional response parameter. It depends on the protocol definitions:

rangingDataCommon

Parameters

Name	Required	Type	Description
subscribe	Optional	Boolean	Subscribe for notifications on changes in the values. Possible values are: true: Subscribed. false: Not subscribed.

Name

Required

Type

Description

Optional

Boolean

Subscribe for notifications on changes in the values.

Possible values are:

true: Subscribed.
false: Not subscribed.

Call Returns

Name	Required	Type	Description
sessionId	Required	Number (int16_t)	The session ID to be handled.
rangingInfo	Optional	Object: rangingInfo	The ranging information received from the UWB module.
subscribed	Required	Boolean	Indicates the status of the operation.
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Operation is successful. false: Operation has failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	The reason for the failure of the operation.

Subscription Returns

Name	Required	Type	Description
subscribed	Required	Boolean	Indicates the status of the operation.
returnValue	Required	Boolean	Indicates the status of the operation.
sessionId	Required	Number (int16_t)	The session ID to be handled.
rangingInfo	Optional	Object: rangingInfo	The ranging information received from the UWB module.

Example

Example scenario

# luna-send -n 1 -f luna://com.webos.service.uwb/getRangingInfo '{}'

Response:

{
"subscribed": false,
"returnValue": true,
"sessionId": 0,
"rangingInfo": {
"rangingDataCommon": [
{
"remoteDeviceAddress": "01",
"receivedCommonData": [
{
...
}
],
"status": "Success"
}
]
}
}

Objects

rangingInfo

Ranging information that was received from UWB module

Name	Required	Type	Description
rangingDataCommon	Optional	Object array: rangingDataCommon	The ranging information received from UWB module for common standard protocol.

rangingDataCommon

Ranging information for common standard protocol.

Name	Required	Type	Description
remoteDeviceAddress	Required	String	The address of the remote device.
status	Required	String	The status of the ranging measurement. Possible values are: Success: Ranging was successful. OutOfRange: The remote device is out of range. UnknownError: Unknown failures.
receivedCommonData	Optional	Object: receivedCommonData	The ranging information from the UWB module.

Name

Required

Type

Description

remoteDeviceAddress

Required

String

The address of the remote device.

status

Required

String

The status of the ranging measurement.

Possible values are:

Success: Ranging was successful.
OutOfRange: The remote device is out of range.
UnknownError: Unknown failures.

receivedCommonData

Optional

Object: receivedCommonData

The ranging information from the UWB module.

receivedCommonData

Provide a ranging information from the UWB module

Name	Required	Type	Description
elapsedRealTimeNanos	Optional	Number (int32_t)	The elapsed real time in nanoseconds when the ranging measurement occurred.
distanceMeasure	Optional	Object: distanceMeasure	The values for calculating distance.
aoaMeasure	Optional	Object: aoaMeasure	The values for calculating altitude angle.

distanceMeasure

The values for calculating distance.

Name	Required	Type	Description
meter	Required	Number (uint64_t)	The distance value
errorMeter	Optional	Number (uint64_t)	The value for calculating exact distance
confidenceLevel	Optional	Number (uint64_t)	The Confidence level of the meter

aoaMeasure

The values for calculating altitude angle.

Name	Required	Type	Description
aziMeasurement	Optional	Object: angleMeasure	Azimuth angle measurement.
altiMeasurement	Optional	Object: angleMeasure	Altitude angle measurement.

angleMeasure

Indicates angle measurement of AoA (Angle of Arrival) in ranging information for common standard protocol.

Name	Required	Type	Description
radian	Required	Number (uint64_t)	The radian value
errorRadian	Optional	Number (uint64_t)	The value for calculating exact radian
confidenceLevel	Optional	Number (uint64_t)	The confidence level of the radian value