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

subscribeOptionalBoolean

Subscribe for notifications on changes in the values.

Possible values are:

  • true: Subscribed.
  • false: Not subscribed.

Call Returns

Name

Required

Type

Description

serviceAvailabilityRequiredBoolean

Indicates the state of UWB service. 

Possible values are:

  • true: Service is available.
  • false: Service is not available.
stateChangeReasonOptionalString

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.
returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

The reason for the failure of the operation.

subscribedRequiredBoolean

Indicates if subscribed to get notifications.

Subscription Returns

Name

Required

Type

Description

serviceAvailabilityRequiredBoolean

Indicates the state of UWB service.

stateChangeReasonOptionalString

Indicates the reason why the state has been changed.

subscribedRequiredBoolean

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

subscribeOptionalBoolean

Subscribe for notifications on changes in the values.

Possible values are:

  • true: Subscribed.
  • false: Not subscribed.

Call Returns

Name

Required

Type

Description

modStateOptionalBoolean

Indicates the state of UWB module.

Possible values are:

  • true: Module is normal.
  • false: Module is not normally initiated.
fwVersionOptionalString

The firmware version of UWB module.

fwCrcOptionalString

The firmware CRC of UWB module.

returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

The reason for the failure of the operation.

Subscription Returns

Name

Required

Type

Description

modStateOptionalBoolean

Indicates the state of UWB module.

fwVersionOptionalString

The firmware version of UWB module.

fwCrcOptionalString

The firmware CRC of UWB module.

subscribedRequiredBoolean

Indicates if subscribed to get notifications.

returnValueRequiredBoolean

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

subscribeOptionalBoolean

Subscribe for notifications on changes in the values.

Possible values are:

  • true: Subscribed.
  • false: Not subscribed.

Call Returns

Name

Required

Type

Description

sessionIdRequiredNumber (int16_t)

The session ID to be handled.

rangingInfoOptionalObject: rangingInfo

The ranging information received from the UWB module.

subscribedRequiredBoolean

Indicates the status of the operation. 

returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

The reason for the failure of the operation.

Subscription Returns

Name

Required

Type

Description

subscribedRequiredBoolean

Indicates the status of the operation. 

returnValueRequiredBoolean

Indicates the status of the operation.

sessionIdRequiredNumber (int16_t)

The session ID to be handled.

rangingInfoOptionalObject: 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

rangingDataCommonOptionalObject array: rangingDataCommon

The ranging information received from UWB module for common standard protocol.

rangingDataCommon

Ranging information for common standard protocol.

Name

Required

Type

Description

remoteDeviceAddressRequiredString

The address of the remote device.

statusRequiredString

The status of the ranging measurement.

Possible values are:

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

The ranging information from the UWB module.

receivedCommonData

Provide a ranging information from the UWB module

Name

Required

Type

Description

elapsedRealTimeNanosOptionalNumber (int32_t)

The elapsed real time in nanoseconds when the ranging measurement occurred.

distanceMeasureOptionalObject: distanceMeasure

The values for calculating distance.

aoaMeasureOptionalObject: aoaMeasure

The values for calculating altitude angle.

distanceMeasure

The values for calculating distance.

Name

Required

Type

Description

meterRequiredNumber (uint64_t)

The distance value

errorMeterOptionalNumber (uint64_t)

The value for calculating exact distance

confidenceLevelOptionalNumber (uint64_t)

The Confidence level of the meter

aoaMeasure

The values for calculating altitude angle.

Name

Required

Type

Description

aziMeasurementOptionalObject: angleMeasure

Azimuth angle measurement.

altiMeasurementOptionalObject: angleMeasure

Altitude angle measurement.

angleMeasure

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

Name

Required

Type

Description

radianRequiredNumber (uint64_t)

The radian value

errorRadianOptionalNumber (uint64_t)

The value for calculating exact radian

confidenceLevelOptionalNumber (uint64_t)

The confidence level of the radian value

Contents