Location Service (Tracker) Destinations

The Location Service adapter delivers device positions extracted from UDP packets to an AWS Location Service tracker resource using the BatchUpdateDevicePosition API. This is a "no code" integration: the device ID, latitude, longitude, and optional metadata are decoded from the raw packet using Binary Range Expressions (BREX) and written straight to the tracker. It is ideal for GPS trackers, asset tags, fleet telemetry, and other location-reporting devices that speak a compact binary protocol over UDP.

Because the integration only writes positions and generates no reply, pair it with a Lambda or Step Functions destination (via a composite destination) if your devices expect an acknowledgement.

Background: Trackers and Filtering

AWS Location Service organizes device positions into tracker resources. Each call to BatchUpdateDevicePosition records the current position of one or more devices on a tracker, keyed by a device ID that you choose. Trackers can be linked to geofence collections to evaluate enter/exit events, and their history can be queried with GetDevicePosition and GetDevicePositionHistory.

Trackers support position filtering to control which updates are stored, which reduces cost and noise from chatty devices:

• TimeBased - stores at most one position per device roughly every 30 seconds.
• DistanceBased - ignores updates that move the device less than 30 meters.
• AccuracyBased - ignores updates that fall within the measured accuracy of the previous position (this is where the optional AccuracyExpression becomes useful).

Position filtering is configured on the tracker resource itself, not on the destination. For the full details, see the AWS documentation on position filtering and Amazon Location Service.

Required Arguments

All three of the following BREX expressions are required. If any is missing, the destination will not be created.

• DeviceIdExpression - extracts the device identifier. Integer results are rendered as their decimal string, utf8 results as text, and any other result as an uppercase hex string.
• LatitudeExpression - extracts the latitude. The extracted value is converted to a double and scaled (see below).
• LongitudeExpression - extracts the longitude, scaled the same way as latitude.

Latitude/Longitude Scaling

Latitude and longitude are provided to the AWS API as decimal-degree double values. Binary protocols rarely transmit floating point degrees directly -- they pack coordinates into fixed-width integers to save bytes. UDP Gateway converts the BREX-extracted value into degrees by multiplying it by a scale factor. How that scale factor is chosen depends on whether you set ScaleFactor explicitly:

Explicit Scaling (ScaleFactor)

When you set the optional ScaleFactor argument to a number, that single factor is applied to both the latitude and longitude values regardless of their BREX type:

degrees = extracted_integer_value * ScaleFactor

Use this when your device documents a fixed encoding. For example, a device that transmits coordinates as signed integers of microdegrees (millionths of a degree) would use:

{
  "LatitudeExpression": "i32le[4:8]",
  "LongitudeExpression": "i32le[8:12]",
  "ScaleFactor": 0.000001
}

A raw value of 47605000 then becomes 47.605 degrees.

Default Scaling (by BREX value type)

If you do not set ScaleFactor, UDP Gateway derives the scale automatically from the BREX value type of the extracted coordinate. The convention treats the integer as a fraction of the full angular range that the type can represent:

• Unsigned types map the full range of the type onto [0, 360) degrees (i.e. scale = 360 / 2^bits).
• Signed types map onto [-180, 180) degrees (i.e. scale = 180 / 2^(bits - 1)).

There is one special case: if the expression yields a utf8 value, it is parsed as a decimal floating point number and used as-is (no scaling is applied). This lets devices that send coordinates as text (e.g. "47.605") work without any scale configuration.

Rule of thumb: choose the BREX type that matches your protocol's fixed-point encoding and let default scaling do the work; reach for ScaleFactor only when your encoding does not fit the “fraction of the full range” model (for example, integer microdegrees or centidegrees).

Optional Arguments

Accuracy

AccuracyExpression extracts a horizontal accuracy value (in meters) for each position. Integer and utf8 (parsed as float) results are supported. Accuracy is most useful in combination with a tracker configured for AccuracyBased position filtering.

Sample Time

TimestampExpression extracts the time the position was sampled by the device. Without it, the packet's arrival time at UDP Gateway is used. Interpretation depends on the extracted type:

• Integer results are treated as a Unix epoch value. TimestampTimeUnit selects the unit -- "seconds" (default) or "milliseconds".
• utf8 results are parsed as a date/time string; if parsing fails, the arrival time is used.

User-Defined Position Properties

PositionPropertyExpressions is a map of property name to BREX expression. Each entry attaches an arbitrary string metadata value to the device position (for example a battery level, speed, heading, or firmware version). Values are rendered the same way as the device ID: integers as decimal strings, utf8 as text, everything else as hex.

Limit: AWS Location Service accepts a maximum of 3 position properties per device position update. UDP Gateway enforces this limit -- if you define more than three, a warning is logged and only the first three non-empty expressions are used.

Example Configuration

The following destination decodes a compact telemetry packet: a two-character device ID, little-endian signed 16-bit latitude and longitude, and two user-defined properties.

{
  "DestinationArn": { "Fn::GetAtt": ["Tracker", "Arn"] },
  "Role": { "Arn": { "Fn::GetAtt": ["DestinationRole", "Arn"] } },
  "Batching": { "Count": 10, "TimeoutInSeconds": 0.1 },
  "Arguments": {
    "DeviceIdExpression": "utf8[0:2]",
    "LatitudeExpression": "i16le[2:4]",
    "LongitudeExpression": "i16le[4:6]",
    "PositionPropertyExpressions": {
      "battery": "u16le[6:8]",
      "status": "utf8[8:10]"
    }
  }
}

Here the i16le coordinates use default scaling (180 / 32768), so the full signed 16-bit range maps to [-180, 180) degrees.

Things to Know About Location Service Destinations

• The ARN must use the geo service identifier and name a tracker/ resource.
• The destination's IAM role must allow geo:BatchUpdateDevicePosition on the tracker.
• No response is generated. Combine with a Lambda or Step Functions destination if devices need an acknowledgement.
• The Formatter setting is ignored -- values come directly from BREX evaluation.
• A single BatchUpdateDevicePosition call carries at most 10 device positions. UDP Gateway chunks larger batches into groups of 10 and keeps only the newest sample per device in each batch.
• At most 3 PositionPropertyExpressions are honored per the AWS API limit.
• Configure position filtering on the tracker to control storage cost for chatty devices.

See the Location Service integration in action in our Location Service example, a no-code CloudFormation template that tracks device positions decoded from UDP packets.