| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Typedefs | Enumerations | Functions
Location and Navigation Service
BLE Services

Location and Navigation Service module. More...

## Data Structures
struct | ble_lns_evt_t
| Location and Navigation event structure. When an event occurs, the data structures of the module are automatically updated. More...
struct | notification_t
struct | ble_lns_init_s
| Location and Navigation Service init structure. This structure contains all options and data needed to initialize the service. More...
struct | ble_lns_route_t
| Definition of a navigation route. More...
struct | ble_lns_s
| Location and Navigation Service structure. This structure contains various status information for the service. More...
struct | ble_lns_loc_speed_s
| Location and Speed data structure. More...
struct | ble_lns_pos_quality_s
| Position quality structure. More...
struct | ble_lns_navigation_s
| Navigation data structure. More...

## Typedefs
typedef struct ble_lns_init_s | ble_lns_init_t
typedef struct ble_lns_s | ble_lns_t
typedef struct ble_lns_loc_speed_s | ble_lns_loc_speed_t
typedef struct ble_lns_pos_quality_s | ble_lns_pos_quality_t
typedef struct ble_lns_navigation_s | ble_lns_navigation_t
typedef void(* | ble_lns_evt_handler_t )(ble_lns_t const *p_lns, ble_lns_evt_t const *p_evt)
| Location and Navigation Service event handler type.

## Enumerations
enum | ble_lns_evt_type_t { BLE_LNS_CTRLPT_EVT_INDICATION_ENABLED, BLE_LNS_CTRLPT_EVT_INDICATION_DISABLED, BLE_LNS_LOC_SPEED_EVT_NOTIFICATION_ENABLED, BLE_LNS_LOC_SPEED_EVT_NOTIFICATION_DISABLED, BLE_LNS_NAVIGATION_EVT_NOTIFICATION_ENABLED, BLE_LNS_NAVIGATION_EVT_NOTIFICATION_DISABLED }
| Location and Navigation event type. This list defines the possible events types from the Location and Navigation Service. More...
enum | ble_lns_pos_status_type_t { BLE_LNS_NO_POSITION = 0, BLE_LNS_POSITION_OK = 1, BLE_LNS_ESTIMATED = 2, BLE_LNS_LAST_KNOWN_POSITION = 3 }
| Position status. This enumeration defines how to interpret the position data.
enum | ble_lns_speed_distance_format_t { BLE_LNS_SPEED_DISTANCE_FORMAT_2D = 0, BLE_LNS_SPEED_DISTANCE_FORMAT_3D = 1 }
| The format of the position and speed measurements.
enum | ble_lns_elevation_source_t { BLE_LNS_ELEV_SOURCE_POSITIONING_SYSTEM = 0, BLE_LNS_ELEV_SOURCE_BAROMETRIC = 1, BLE_LNS_ELEV_SOURCE_DATABASE_SERVICE = 2, BLE_LNS_ELEV_SOURCE_OTHER = 3 }
| Elevation source.
enum | ble_lns_heading_source_t { BLE_LNS_HEADING_SOURCE_MOVEMENT = 0, BLE_LNS_HEADING_SOURCE_COMPASS = 1 }
| Heading source.
enum | ble_lns_nav_indicator_type_t { BLE_LNS_NAV_TO_WAYPOINT = 0, BLE_LNS_NAV_TO_DESTINATION = 1 }
| Navigation indicator type.

## Functions
ret_code_t | ble_lns_init (ble_lns_t *p_lns, const ble_lns_init_t *p_lns_init)
| Function for initializing the Location and Navigation Service. More...
void | ble_lns_on_ble_evt (ble_lns_t *p_lns, ble_evt_t const *p_ble_evt)
| Function for handling Location and Navigation Service BLE stack events. More...
ret_code_t | ble_lns_loc_speed_send (ble_lns_t *p_lns)
| Function for sending location and speed data if notification has been enabled. More...
ret_code_t | ble_lns_navigation_send (ble_lns_t *p_lns)
| Function for sending navigation data if notification has been enabled. More...
ret_code_t | ble_lns_add_route (ble_lns_t *p_lns, ble_lns_route_t *p_route)
| Function for adding a route to the Location and Navigation Service. More...
ret_code_t | ble_lns_remove_route (ble_lns_t *p_lns, uint16_t route_id)
| Function for removing a route from the Location and Navigation Service. More...

## Detailed Description

Location and Navigation Service module.

This module implements the Location and Navigation Service with the Location and Speed, Position Quality, Feature, Control Point, and Navigation characteristics.

If an event handler is supplied by the application, the Location and Navigation Service will generate Location and Navigation Service events to the application.

Note
  The application must propagate BLE stack events to the Location and Navigation Service module by calling ble_lns_on_ble_evt() from the from the ble_stack_handler callback.

## Enumeration Type Documentation

enum ble_lns_evt_type_t

Location and Navigation event type. This list defines the possible events types from the Location and Navigation Service.

Enumerator
BLE_LNS_CTRLPT_EVT_INDICATION_ENABLED | Control Point value indication was enabled.
BLE_LNS_CTRLPT_EVT_INDICATION_DISABLED | Control Point value indication was disabled.
BLE_LNS_LOC_SPEED_EVT_NOTIFICATION_ENABLED | Location and Speed value notification was enabled.
BLE_LNS_LOC_SPEED_EVT_NOTIFICATION_DISABLED | Location and Speed value notification was disabled.
BLE_LNS_NAVIGATION_EVT_NOTIFICATION_ENABLED | Navigation value notification was enabled.
BLE_LNS_NAVIGATION_EVT_NOTIFICATION_DISABLED | Navigation value notification was disabled.

## Function Documentation

ret_code_t ble_lns_add_route | ( | ble_lns_t * | p_lns,
|  | ble_lns_route_t * | p_route
| ) |  |

Function for adding a route to the Location and Navigation Service.

Parameters

  [in] | p_lns | Location and Navigation Service structure.
  [in,out] | p_route | The new route to be added. The route ID is updated.

Return values

  NRF_SUCCESS | If the route was added successfully.
  NRF_ERROR_NULL | If a NULL parameter was provided.
  NRF_ERROR_NOT_SUPPORTED | If the navigation characteristic is absent.
  NRF_ERROR_NO_MEM | If there is no memory left.
  NRF_ERROR_INTERNAL | If there is an inconsistency in the routes table.

ret_code_t ble_lns_init | ( | ble_lns_t * | p_lns,
|  | const ble_lns_init_t * | p_lns_init
| ) |  |

Function for initializing the Location and Navigation Service.

Parameters

  [out] | p_lns | Location and Navigation Service structure. This structure must be supplied by the application. It is initialized by this function, and will later be used to identify this particular service instance.
  [in] | p_lns_init | Information needed to initialize the service.

Return values

  NRF_SUCCESS | If the service was initialized successfully.
  NRF_ERROR_NULL | If a NULL parameter was provided.
  NRF_INVALID_PARAMS | If there is an inconsistency in the initialization structure.

Returns
  Otherwise, an error code from either sd_ble_gatts_service_add() or sd_ble_gatts_characteristic_add() is returned.

ret_code_t ble_lns_loc_speed_send | ( | ble_lns_t * | p_lns | ) |

Function for sending location and speed data if notification has been enabled.

The application calls this function after having performed a location and speed determination. If notification has been enabled, the location and speed data is encoded and sent to the client.

Parameters

  [in] | p_lns | Location and Navigation Service structure holding the location and speed data.

Return values

  NRF_SUCCESS | If the data was sent successfully.
  NRF_ERROR_NULL | If a NULL parameter was provided.
  NRF_ERROR_INVALID_STATE | If notification is disabled.

ret_code_t ble_lns_navigation_send | ( | ble_lns_t * | p_lns | ) |

Function for sending navigation data if notification has been enabled.

The application calls this function after having performed a navigation determination. If notification has been enabled, the navigation data is encoded and sent to the client.

Parameters

  [in] | p_lns | Location and Navigation Service structure holding the navigation data.

Return values

  NRF_SUCCESS | If the data was sent successfully.
  NRF_ERROR_NULL | If a NULL parameter was provided.
  NRF_ERROR_NOT_SUPPORTED | If the navigation characteristic is absent.
  NRF_ERROR_INVALID_STATE | If navigation is not running or notification is disabled.

void ble_lns_on_ble_evt | ( | ble_lns_t * | p_lns,
|  | ble_evt_t const * | p_ble_evt
| ) |  |

Function for handling Location and Navigation Service BLE stack events.

This function handles all events from the BLE stack that are of interest to the Location and Navigation Service.

Note
  The function returns when a NULL parameter is provided.

Parameters

  [in] | p_lns | Location and Navigation Service structure.
  [in] | p_ble_evt | Event received from the BLE stack.

ret_code_t ble_lns_remove_route | ( | ble_lns_t * | p_lns,
|  | uint16_t | route_id
| ) |  |

Function for removing a route from the Location and Navigation Service.

Parameters

  [in] | p_lns | Location and Navigation Service structure.
  [in] | route_id | The ID of the route to be removed.

Return values

  NRF_SUCCESS | If the route was removed successfully.
  NRF_ERROR_NULL | If a NULL parameter was provided.
  NRF_ERROR_NOT_SUPPORTED | If the navigation characteristic is absent.
  NRF_INVALID_PARAM | If the route ID does not exist.