Resolving device location using AWS IoT Core Device Location MQTT topics
You can use reserved MQTT topics to get the latest location information for your devices with the AWS IoT Core Device Location feature.
Format of device location MQTT topics
Reserved topics for AWS IoT Core Device Location use the following prefix:
$aws/device_location/
{customer_device_id}
/
To create a complete topic, first replace
with your unique
ID that you use for identifying your device. We recommend that you specify the
customer_device_id
WirelessDeviceId
, such as for LoRaWAN and Sidewalk devices, and
, if your device is
registered as an AWS IoT thing. You then append the topic with the topic stub, such as
thingName
get_position_estimate
or
get_position_estimate/accepted
as shown in the following
section.
Note
The
can only
contain letters, numbers, and dashes. When subscribing to device location
topics, you can only use the plus sign (+) as a wildcard character. For example,
you can use the {customer_device_id}
+
wildcard for the
to obtain
the location information for your devices. When you subscribe to the topic
{customer_device_id}
$aws/device_location/
,
a message will be published with the location information for devices that match
any device ID if it was successfully resolved.+
/get_position_estimate/accepted
The following are the reserved topics used to interact with AWS IoT Core Device Location.
Device location MQTT topics | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Topic | Allowed operations | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
$aws/device_location/ |
Publish |
A device publishes to this topic to get the scanned raw measurement data to be resolved by AWS IoT Core Device Location. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
$aws/device_location/ |
Subscribe |
AWS IoT Core Device Location publishes the location information to this topic when it successfully resolves the device location. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
$aws/device_location/ |
Subscribe |
AWS IoT Core Device Location publishes the error information to this topic when it fails to resolve the device location. |
Policy for device location MQTT topics
To receive messages from device location topics, your device must use a policy that allows it to connect to the AWS IoT device gateway and subscribe to the MQTT topics.
The following is an example of the policy required for receiving messages for the various topics.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:
region
:account
:topic/$aws/device_location/customer_device_id
/get_position_estimate" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region
:account
:topic/$aws/device_location/customer_device_id
/get_position_estimate/accepted", "arn:aws:iot:region
:account
:topic/$aws/device_location/customer_device_id
/get_position_estimate/rejected" ] }, { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:region
:account
:topicfilter/$aws/device_location/customer_device_id
/get_position_estimate/accepted", "arn:aws:iot:region
:account
:topicfilter/$aws/device_location/customer_device_id
/get_position_estimate/rejected" ] } ] }
Device location topics and payload
The following shows the AWS IoT Core Device Location topics, the format of their message payload, and an example policy for each topic.
/get_position_estimate
Publish a message to this topic to get the raw measurement data from the device to be resolved by AWS IoT Core Device Location.
$aws/device_location/
customer_device_id
/get_position_estimate
AWS IoT Core Device Location responds by publishing to either /get_position_estimate/accepted or /get_position_estimate/rejected.
Note
The message published to this topic must be a valid JSON payload. If the input message is not in valid JSON format, you won't get any response. For more information, see Message payload.
The message payload format follows a similar structure as the
AWS IoT Wireless API operation request body, GetPositionEstimate
. It contains:
-
An optional
Timestamp
string, which corresponds to the date and time the location was resolved. TheTimestamp
string can have a minimum length of 1 and maximum length of 10. -
An optional
MessageId
string, which can be used to map the request to the response. If you specify this string, the message published to theget_position_estimate/accepted
orget_position_estimate/rejected
topics will contain thisMessageId
. TheMessageID
string can have a minimum length of 1 and maximum length of 256. -
The measurement data from the device that contains one or more of the following measurement types:
The following shows a sample message payload.
{ "Timestamp":
"1664313161"
, "MessageId":"ABCD1"
, "WiFiAccessPoints": [ { "MacAddress": "A0:EC:F9:1E:32:C1
", "Rss":-66
} ], "Ip":{ "IpAddress":"54.192.168.0"
}, "Gnss":{ "Payload":"8295A614A2029517F4F77C0A7823B161A6FC57E25183D96535E3689783F6CA48"
, "CaptureTime":1354393948
} }
The following is an example of the required policy:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:
region
:account
:topic/$aws/device_location/customer_device_id
/get_position_estimate" ] } ] }
/get_position_estimate/accepted
AWS IoT Core Device Location publishes a response to this topic when returning the resolved
location information for your device. The location information is returned in
GeoJSON format
$aws/device_location/
customer_device_id
/get_position_estimate/accepted
The following shows the message payload and an example policy.
The following is an example of the message payload in GeoJSON format.
If you specified a MessageId
in your raw measurement data
and AWS IoT Core Device Location resolved the location information successfully, then the
message payload returns the same MessageId
information.
{ "coordinates": [ 13.37704086303711, 52.51865005493164 ], "type": "Point", "properties": { "verticalAccuracy": 707, "verticalConfidenceLevel": 0.68, "horizontalAccuracy": 389, "horizontalConfidenceLevel": 0.68, "country": "USA", "state": "CA", "city": "Sunnyvalue", "postalCode": "91234", "timestamp": "2022-11-18T14:03:57.391Z", "messageId": "ABCD1" } }
The following is an example of the required policy:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:
region
:account
:topicfilter/$aws/device_location/customer_device_id
/get_position_estimate/accepted" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region
:account
:topic/$aws/device_location/customer_device_id
/get_position_estimate/accepted" ] } ] }
/get_position_estimate/rejected
AWS IoT Core Device Location publishes an error response to this topic when it fails to resolve the device location.
$aws/device_location/
customer_device_id
/get_position_estimate/rejected
The following shows the message payload and example policy. For information about the errors, see Troubleshooting errors when resolving the location.
The following is an example of the message payload that provides the
error code and message, which indicates why AWS IoT Core Device Location failed to resolve
the location information. If you specified a MessageId
when
providing your raw measurement data and AWS IoT Core Device Location failed to resolve the
location information, then the same MessageId
information
will be returned in the message payload.
{ "errorCode": 500, "errorMessage":"Internal server error", "messageId": "ABCD1" }
The following is an example of the required policy:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:
region
:account
:topicfilter/$aws/device_location/customer_device_id
/get_position_estimate/rejected" ] }, { "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region
:account
:topic/$aws/device_location/customer_device_id
/get_position_estimate/rejected" ] } ] }