Module: Toybox.Position

Overview

The Position module provides an interface for location information and positioning sensors.

This module also provides two sets of constants:

  • GEO: Used to specify the Location formatting.

  • QUALITY: Represents the GPS fix quality when the Location information was calculated

Example:

using Toybox.Position;
using Toybox.System;
Position.enableLocationEvents(Position.LOCATION_ONE_SHOT, method(:onPosition));
function onPosition(info) {
    var myLocation = info.position.toDegrees();
    System.println("Latitude: " + myLocation[0]); // e.g. 38.856147
    System.println("Longitude: " + myLocation[1]); // e.g -94.800953
}

Since:

API Level 1.0.0

Classes Under Namespace

Classes: Info, Location

Constant Summary

Constellation

Name Value Since Description
CONSTELLATION_GPS 0

API Level 3.2.0

Use the GPS satellite constellation

CONSTELLATION_GLONASS 1

API Level 3.2.0

Use the GLONASS satellite constellation

CONSTELLATION_GALILEO 2

API Level 3.2.0

Use the GALILEO satellite constellation

CoordinateFormat

Name Value Since Description
GEO_DEG 0

API Level 1.0.0

The decimal degree format: ddd.dddddd (e.g. 38.278652)

GEO_DM 1

API Level 1.0.0

The degrees/decimal minutes format: dddmm.mmm (e.g 38 27.865')

GEO_DMS 2

API Level 1.0.0

degrees/minutes/seconds (DMS) format: ddd mm ss (e.g. 38 27' 8")

GEO_MGRS 3

API Level 1.0.0

Military Grid Reference System, or MGRS (e.g. 4QFJ12345678)

Quality

Name Value Since Description
QUALITY_NOT_AVAILABLE 0

API Level 1.0.0

GPS is not available

QUALITY_LAST_KNOWN 1

API Level 1.0.0

The Location is based on the last known GPS fix.

QUALITY_POOR 2

API Level 1.0.0

The Location was calculated with a poor GPS fix. Only a 2-D GPS fix is available, likely due to a limited number of tracked satellites.

QUALITY_USABLE 3

API Level 1.0.0

The Location was calculated with a usable GPS fix. A 3-D GPS fix is available, with marginal HDOP (horizontal dilution of precision)

QUALITY_GOOD 4

API Level 1.0.0

The Location was calculated with a good GPS fix. A 3-D GPS fix is available, with good-to-excellent HDOP (horizontal dilution of precision).

LocationAcquisitionType

Name Value Since Description
LOCATION_ONE_SHOT 0

API Level 1.0.0

Enables a one-time Location acquisition

LOCATION_CONTINUOUS 1

API Level 1.0.0

Enables continuous Location tracking

LOCATION_DISABLE 2

API Level 1.0.0

Disables Location tracking

PositioningMode

Name Value Since Description
POSITIONING_MODE_NORMAL 0

Standard positioning mode used by default for fitness activities

POSITIONING_MODE_AVIATION 1

Enable special mode for aviation use-cases that require support for higher altitudes.

Instance Method Summary collapse

Instance Method Details

createBoundingBox(locations as Lang.Array<Position.Location>) as Lang.Array<Position.Location> or Null

Create a bounding box from an array of Location objects.

Parameters:

Returns:

  • Lang.Array

    Array of Location objects that specify the bounds of the input array or null if the the input array is empty. The first element describes the top left corner, the second describes the bottom right.

Since:

API Level 3.0.3

enableLocationEvents(options as { :acquisitionType as Position.LocationAcquisitionType, :constellations as Lang.Array<Position.Constellation> } or Position.LocationAcquisitionType, listener as Lang.Method(loc as Position.Info) as Void) as Void

Request a Location event.

Using this API requires enabling the Positioning Permission. Only Device Apps and Widgets may use this API.

Note:

Passing an options Dictionary is only supported with ConnectIQ 3.2.0 and later.

Note:

Will cause an app crash if called from audio content provider, data field, or watch face app

Parameters:

  • options(Lang.Number, Lang.Dictionary)

    A LOCATION_* value or Toybox::Lang::Dictionary of options.

    • :acquisitionType(Lang.Number)

      A LOCATION_* enum value indicating the position acquisition type to use.

    • :constellations(Lang.Array)

      An array of CONSTELLATION_* enum values specifying what constellations to enable. If not provided, CONSTELLATION_GPS will be used by default.

    • :mode(Lang.Number)

      a POSITIONING_MODE_* value specifying the mode to use. If null POSITIONING_MODE_NORMAL will be used by default.

  • listener(Lang.Method)

    A reference to a listener method:

    • Called when location updates are received

    • Receives a Position.Info object

Example:

using Toybox.Position;

// Single location update using GPS
Position.enableLocationEvents(Position.LOCATION_ONE_SHOT, method(:onPosition));
function onPosition(info) {
    var myLocation = info.position.toDegrees();
}

// Continuous location updates using GPS or GALILEO
Position.enableLocationEvents({
        :acquisitionType => Position.LOCATION_CONTINUOUS,
        :constellations => [ Position.CONSTELLATION_GPS, Position.CONSTELLATION_GALILEO ]
    },
    method(:onPosition)
);

function onPosition(info) {
    var myLocation = info.position.toDegrees();
}

Supported Devices:

Since:

API Level 1.0.0

Throws:

  • (Lang.InvalidValueException)

    Thrown if :acquisitionType is invalid, if a specific CONSTELLATION_* value is not supported by a device, or if an invalid combination of constellation values are specified.

getInfo() as Position.Info

Get the current Position.Info.

Using this API requires enabling the Positioning Permission. This is useful for retrieving the current position info either on demand or periodically within a Timer.

Example:

Get position info once per second

using Toybox.Position;
using Toybox.System;
using Toybox.Timer;
var dataTimer = new Timer.Timer();
dataTimer.start(method(:timerCallback), 1000, true); // A one-second timer
function timerCallback() {
    var positionInfo = Position.getInfo();
    if (positionInfo has :altitude && positionInfo.altitude != null) {
        var altitude = positionInfo.altitude;
        System.println("Altitude: " + altitude);
    }
}

Supported Devices:

Returns:

Since:

API Level 1.0.0

parse(string as Lang.String, format as Position.CoordinateFormat) Position.Location

Convert a String to a Location object.

The input String must be in one of the four formats described by the Position.GEO_* constants.

Parameters:

Example:

using Toybox.Position;
using Toybox.System;
var locString = "38.856147, -94.800953";
var myLocation = Position.parse(locString, Position.GEO_DEG);
System.println(myLocation.toRadians()); // [0.678168, -1.654589]

Returns:

  • Position.Location

    A Location object representing the position described by the input String

Since:

API Level 1.0.0


Generated Jul 7, 2021 10:36:26 AM