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

Examples:

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:

  • 1.0.0

Defined Under Namespace

Classes: Info, Location

Constant Summary

GEO_DEG = 0

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

See Also:

Since:

  • 1.0.0

GEO_DM = 1

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

Since:

  • 1.0.0

GEO_DMS = 2

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

Since:

  • 1.0.0

GEO_MGRS = 3

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

See Also:

Since:

  • 1.0.0

QUALITY_NOT_AVAILABLE = 0

GPS is not available

Since:

  • 1.0.0

QUALITY_LAST_KNOWN = 1

The Location is based on the last known GPS fix.

Since:

  • 1.0.0

QUALITY_POOR = 2

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.

Since:

  • 1.0.0

QUALITY_USABLE = 3

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

See Also:

Since:

  • 1.0.0

QUALITY_GOOD = 4

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

See Also:

Since:

  • 1.0.0

LOCATION_ONE_SHOT = 0

Enables a one-time Location acquisition

Since:

  • 1.0.0

LOCATION_CONTINUOUS = 1

Enables continuous Location tracking

Since:

  • 1.0.0

LOCATION_DISABLE = 2

Disables Location tracking

Since:

  • 1.0.0

Instance Method Summary collapse

Instance Method Details

createBoundingBox(locations) ⇒ Toybox::Lang::Array

Create a bounding box from an array of Location objects.

Parameters:

Returns:

  • (Toybox::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:

  • 3.0.3


8442
8443
# File 'Monkeybrains.rb', line 8442

def createBoundingBox(locations)
end

enableLocationEvents(type, listener) ⇒ Object

Request a Location event.

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

Examples:

using Toybox.Position;
Position.enableLocationEvents(Position.LOCATION_ONE_SHOT, method(:onPosition));
function onPosition(info) {
    var myLocation = info.position.toDegrees();
}

Parameters:

  • type (Toybox::Lang::Number)

    A LOCATION_* value:

    • LOCATION_ONE_SHOT for a single location request

    • LOCATION_CONTINUOUS to enable location tracking

    • LOCATION_DISABLE to turn off location tracking

  • listener (Toybox::Lang::Method)

    A reference to a listener method:

    • Called when location updates are received

    • Receives a Position.Info object

Since:

  • 1.0.0


8344
8345
# File 'Monkeybrains.rb', line 8344

def enableLocationEvents(type, listener)
end

getInfoToybox::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.

Examples:

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);
    }
}

Returns:

Since:

  • 1.0.0


8431
8432
# File 'Monkeybrains.rb', line 8431

def getInfo()
end

parse(string, format) ⇒ Toybox::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.

Examples:

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]

Parameters:

Returns:

Since:

  • 1.0.0


8308
8309
# File 'Monkeybrains.rb', line 8308

def parse(string, format)
end