Skip to content

Commit 5d11443

Browse files
hasheddanhasheddan
committed
location: update all location docs to reflect new structure
Updates all Golioth Location documentation to reflect its new structure ahead of General Availability. Devices now interact with Golioth Location via Pipelines, creating a much more flexible and robust solution. Signed-off-by: Daniel Mangum <georgedanielmangum@gmail.com>
1 parent ed6738d commit 5d11443

8 files changed

Lines changed: 243 additions & 161 deletions

File tree

‎docs/application-services/3-location/2-network-based-positioning.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: Network-Based Positioning
3+
---
4+
5+
:::usage
6+
Network-based positioning with Golioth Location incures usage costs. See
7+
[Golioth pricing](https://golioth.io/pricing) for more information.
8+
:::
9+
10+
Devices can obtain their position by streaming information about cell towers,
11+
Wi-Fi access points, or both, to a [Golioth Pipeline](../../data-routing) that
12+
makes use of the [`location`
13+
transformer](../../data-routing/3-transformers/10-location.md). Typically, the
14+
more information that a device can provide, the more accurate the location data
15+
returned will be.
16+
17+
See the
18+
[example](https://github.com/golioth/golioth-firmware-sdk/tree/main/examples/zephyr/location)
19+
in the [Golioth Firmware
20+
SDK](https://docs.golioth.io/firmware/golioth-firmware-sdk) for a demonstration
21+
of how to use network information to obtain device position.
22+
23+
### Use Cases
24+
25+
Network-based positioning is particularly relevant in the following scenarios.
26+
27+
#### Devices without GNSS Capabilities
28+
29+
Adding GNSS support to a device increases BOM cost, and powering GNSS radios can
30+
have a significant negative impact on battery life. For devices that do not
31+
require the most precise location resolution, opting to forego GNSS
32+
capabilities, or opting to use it sparingly, may be optimal. In these cases,
33+
devices can leverage network-based positioning, which is still able to provide
34+
location data with accuracy on the order of tens to hundreds of meters.
35+
36+
#### Indoor Devices and Devices in Urban Locations
37+
38+
Some environments make leveraging GNSS challenging or impossible. Devices that
39+
are typically indoors or in dense urban areas will frequently struggle to
40+
receive signals from GNSS satellites. Network-based positioning is a reliable
41+
alternative, providing highly accurate results in environments where information
42+
about multiple Wi-Fi access points or cell towers can be submitted.
43+
44+
#### Devices Requiring Rapid Location Resolution
45+
46+
Obtaining position via GNSS can take up to 15 minutes in cold start scenarios.
47+
Network-based positioning can resolve location instantly when a connection to
48+
the Golioth cloud platform is already established. Devices with low latency
49+
positioning requirements may opt to use network-based positioning instead of, or
50+
in addition to GNSS capabilities.
51+

‎docs/application-services/3-location/2-resolving.md‎

Lines changed: 0 additions & 38 deletions
This file was deleted.

‎docs/application-services/3-location/3-querying.md‎

Lines changed: 0 additions & 34 deletions
This file was deleted.

‎docs/application-services/3-location/3-tracking.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
title: Tracking Location
3+
---
4+
5+
Whether location is obtained via traditional on-device mechanisms, such as GNSS,
6+
or via Golioth Location's [network-based
7+
positioning](/application-services/location/network-based-positioning)
8+
capabilities, it can be routed and delivered to one or more destinations via
9+
[Golioth Pipelines](/data-routing). For example, if tracking a device's location
10+
over time is necessary, routing location to [LightDB
11+
Stream](/application-services/lightdb-stream) or an external timeseries database
12+
may be required. If it is necessary to make device's aware of their own
13+
position, location information may be routed to [LightDB
14+
State](/application-services/lightdb-state), where it can be accessed by the
15+
device.
16+
17+
Golioth Location also offers built-in storage for the most recent device
18+
position. Routing location information to the [`location` data
19+
destination](/data-routing/destinations/location) will make it available for
20+
visualization in `Location` section of the [Golioth
21+
console](https://docs.golioth.io/getting-started/golioth-console).
22+
23+
Location data for one or more devices can also be retrieved via the [Golioth
24+
Management API](/reference/management-api). See the [OpenAPI
25+
definitions](/reference/management-api/openapi) for more information.

‎docs/application-services/3-location/README.md‎

Lines changed: 7 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -2,43 +2,14 @@
22
title: Golioth Location Overview
33
---
44

5-
## What is Golioth Location?
6-
7-
Golioth Location is a positioning service that enables connected devices to
8-
retrieve their approximate location by submitting network information to the
9-
Golioth cloud platform. The service currently supports resolving position based
10-
on cell tower and Wi-Fi access point data.
11-
125
:::note
13-
Golioth Location is currently limited to members of the [private access
14-
program](https://blog.golioth.io/golioth-location-private-access/).
6+
Golioth Location requires access to a project on the Teams tier or higher. See
7+
[Golioth pricing](https://golioth.io/pricing) for more information.
158
:::
169

17-
### Use Cases
18-
19-
Network-based positioning is particularly relevant in the following scenarios.
20-
21-
#### Devices without GNSS Capabilities
22-
23-
Adding GNSS support to a device increases BOM cost, and powering GNSS radios can
24-
have a significant negative impact on battery life. For devices that do not
25-
require the most precise location resolution, opting to forego GNSS
26-
capabilities, or opting to use it sparingly, may be optimal. In these cases,
27-
devices can leverage network-based positioning, which is still able to provide
28-
location data with accuracy on the order of tens to hundreds of meters.
29-
30-
#### Indoor Devices and Devices in Urban Locations
31-
32-
Some environments make leveraging GNSS challenging or impossible. Devices that
33-
are typically indoors or in dense urban areas will frequently struggle to
34-
receive signals from GNSS satellites. Network-based positioning is a reliable
35-
alternative, providing highly accurate results in environments where information
36-
about multiple Wi-Fi access points or cell towers can be submitted.
37-
38-
#### Devices Requiring Rapid Location Resolution
10+
## What is Golioth Location?
3911

40-
Obtaining position via GNSS can take up to 15 minutes in cold start scenarios.
41-
Network-based positioning can resolve location instantly when a connection to
42-
the Golioth cloud platform is already established. Devices with low latency
43-
positioning requirements may opt to use network-based positioning instead of, or
44-
in addition to GNSS capabilities.
12+
Golioth Location is a comprehensive device positioning service, making it
13+
possible to determine and track device location via a variety of sources,
14+
including GNSS and network information. Devices interact with Golioth Location
15+
through [Golioth Pipelines](/data-routing).

docs/reference/2-device-api/3-api-docs/8-location.md renamed to docs/data-routing/3-transformers/10-location.md

Lines changed: 56 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,62 @@
11
---
2-
title: Location
2+
title: location
33
---
44

5-
[Golioth Location](/application-services/location) API definitions.
5+
| | |
6+
|---|:---:|
7+
|__Latest Version__| `v1.0.0` |
8+
|__Input Content Type__| `application/json` |
9+
|__Output Content Type__| `application/json` |
610

7-
## Interface
8-
9-
| Method | Description | Path | Content Format |
10-
| ----------- | ------------------------------------------------- | ----------------- | -------------- |
11-
| POST | Resolve location using network-based positioning. | `/.l/v1/net` | JSON/CBOR |
12-
13-
14-
## Network Positioning Request Format
15-
16-
Network-based positioning requests may include both cell tower and Wi-Fi access
17-
point information. At least one cell tower or Wi-Fi access point is required for
18-
successful resolution.
11+
The `location` transformer uses [Golioth
12+
Location](../../application-services/3-location) to resolve device position
13+
using network information provided in the data message payload. Network-based
14+
positioning requires information about zero or more cell towers and Wi-Fi access
15+
points. Data must be formatted as described below, and at least one cell tower
16+
or Wi-Fi access point must be provided for successful resolution.
1917

2018
| Attribute | Description |
2119
| --------- | ------------------------------------------------------------ |
2220
| `cell` | Array of cell tower objects. |
2321
| `wifi` | Array of Wi-Fi access point objects. |
2422

23+
#### Cell Tower Format
24+
25+
| Attribute | Description | Required |
26+
|------------|------------------------------------------------------------------------------------|----------|
27+
| `type` | String indicating type of cellular network (`ltecatm` or `nbiot` | X |
28+
| `mcc` | Integer indicating Mobile Country Code. | X |
29+
| `mnc` | Integer indicating Mobile Network Code. | X |
30+
| `id` | Integer indicating EUCID (LTE Cat-M) or Cell ID (NB-Iot). | X |
31+
| `strength` | Integer indicating RSRP (LTE Cat-M) or NRSRP (NB-Iot). (dBm) | |
32+
| `lac` | Integer indicating Tracking Area Code (TAC) | |
33+
| `age` | Integer indicating age of measurement. (ms) | |
34+
| `channel` | Integer indicating EARFCN. | |
35+
| `serving` | Boolean indicate whether device is currently served by the cell. (default: `false`) | |
36+
| `lid` | Integer indicating PCI (LTE Cat-M) or NCID (NB-Iot) | |
37+
38+
#### Wi-Fi Access Point Format
39+
40+
| Attribute | Description | Required |
41+
|-------------|--------------------------------------------------------------------------------------------------|----------|
42+
| `mac` | String indicating access point MAC address. | X |
43+
| `ssid` | String indicating access point Service Set Identifier. | |
44+
| `strength` | Integer indicating signal strength of access point (dBm). | |
45+
| `age` | Integer indicating age of measurement. (ms) | |
46+
| `frequency` | Integer indicating frequency of access point. (MHz) | |
47+
| `channel` | Integer indicating channel number of access point. | |
48+
| `Connected` | Boolean indicating whether device is currently connected to the access point. (default: `false`) | |
49+
2550

26-
An example request with both cellular and Wi-Fi network data is provided below.
51+
### Example Usage
52+
53+
```yaml
54+
transformer:
55+
type: location
56+
version: v1
57+
```
58+
59+
### Example Input
2760
2861
```json
2962
{
@@ -56,47 +89,17 @@ An example request with both cellular and Wi-Fi network data is provided below.
5689
}
5790
```
5891

59-
### Cell Tower Format
60-
61-
| Attribute | Description | Required |
62-
|------------|------------------------------------------------------------------------------------|----------|
63-
| `type` | String indicating type of cellular network (`ltecatm` or `nbiot` | X |
64-
| `mcc` | Integer indicating Mobile Country Code. | X |
65-
| `mnc` | Integer indicating Mobile Network Code. | X |
66-
| `id` | Integer indicating EUCID (LTE Cat-M) or Cell ID (NB-Iot). | X |
67-
| `strength` | Integer indicating RSRP (LTE Cat-M) or NRSRP (NB-Iot). (dBm) | |
68-
| `lac` | Integer indicating Tracking Area Code (TAC) | |
69-
| `age` | Integer indicating age of measurement. (ms) | |
70-
| `channel` | Integer indicating EARFCN. | |
71-
| `serving` | Boolean indicate whether device is currently served by the cell. (default: `false`) | |
72-
| `lid` | Integer indicating PCI (LTE Cat-M) or NCID (NB-Iot) | |
73-
74-
### Wi-Fi Access Point Format
75-
76-
| Attribute | Description | Required |
77-
|-------------|--------------------------------------------------------------------------------------------------|----------|
78-
| `mac` | String indicating access point MAC address. | X |
79-
| `ssid` | String indicating access point Service Set Identifier. | |
80-
| `strength` | Integer indicating signal strength of access point (dBm). | |
81-
| `age` | Integer indicating age of measurement. (ms) | |
82-
| `frequency` | Integer indicating frequency of access point. (MHz) | |
83-
| `channel` | Integer indicating channel number of access point. | |
84-
| `Connected` | Boolean indicating whether device is currently connected to the access point. (default: `false`) | |
85-
86-
## Network Positioning Response Format
87-
88-
| Attribute | Description |
89-
|-----------|---------------------------------------------------------|
90-
| `lat` | Integer indicating latitude of device. (nanodegrees) |
91-
| `lon` | Integer indicating longitude of device. (nanodegrees) |
92-
| `acc` | Integer horizontal positioning accuracy (HPE). (meters) |
92+
### Example Output
9393

94-
An example response is provided below.
94+
While output from the `location` transformer can be transformed further and
95+
routed to any number of destinations, the format of the data returned can be
96+
delivered to the [`location` destination](../4-destinations/15-location.md)
97+
without any modification.
9598

9699
```json
97100
{
98-
"lat": 50664189000,
99-
"lon": 17942112000,
100-
"acc": 65
101+
"latitude": 50.664189000,
102+
"longitude": 17.942112000,
103+
"accuracy": 65
101104
}
102105
```

‎docs/data-routing/4-destinations/15-location.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: location
3+
---
4+
5+
| | |
6+
|---|:---:|
7+
|__Latest Version__| `v1.0.0` |
8+
|__Input Content Type__| `application/json` |
9+
10+
The `location` destination sends data to [Golioth
11+
Location](/application-services/location). Data must arrive as or be transformed
12+
into a JSON object with the following fields to be successfully delivered.
13+
14+
| Attribute | Description |
15+
|-----------------|---------------------------------------------------------|
16+
| `latitude` | Float indicating latitude of device. |
17+
| `longitude` | Float indicating longitude of device. |
18+
| `accuracy` | Integer horizontal positioning accuracy (HPE). (meters) |
19+
20+
In some cases horizontal positioning error (HPE) is unknown or irrelevant and
21+
may be omitted.
22+
23+
### Example Usage
24+
25+
Because Golioth Location is hosted by Golioth, no credentials are required to
26+
deliver data to the service.
27+
28+
```yaml
29+
destination:
30+
type: location
31+
version: v1
32+
```
33+
34+
### Example Input
35+
36+
```json
37+
{
38+
"latitude": 50.664189000,
39+
"longitude": 17.942112000,
40+
"accuracy": 65
41+
}
42+
```
43+
44+
### Example Output
45+
46+
Devices that deliver data to the `location` destination can be displayed on a
47+
map in the [Golioth
48+
console](https://docs.golioth.io/getting-started/golioth-console).
49+
50+
```json
51+
{
52+
"latitude": 50.664189000,
53+
"longitude": 17.942112000,
54+
"accuracy": 65
55+
}
56+
```

0 commit comments

Comments
 (0)