Location and Navigation Service

Location and Navigation Service module. More...

Data Structures
struct	ble_lns_mask_t
	A mask can be used to temporarily enable and disable features of the Location and Speed characteristic. More...
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	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_routes_s
	Definition of a navigation route. More...
struct	ble_lns_ctrlpt_response_t
	Information included in a control point write response indication. 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...

Macros
#define	BLE_LNS_FEATURE_INSTANT_SPEED_SUPPORTED   (0x01 << 0)
#define	BLE_LNS_FEATURE_TOTAL_DISTANCE_SUPPORTED   (0x01 << 1)
#define	BLE_LNS_FEATURE_LOCATION_SUPPORTED   (0x01 << 2)
#define	BLE_LNS_FEATURE_ELEVATION_SUPPORTED   (0x01 << 3)
#define	BLE_LNS_FEATURE_HEADING_SUPPORTED   (0x01 << 4)
#define	BLE_LNS_FEATURE_ROLLING_TIME_SUPPORTED   (0x01 << 5)
#define	BLE_LNS_FEATURE_UTC_TIME_SUPPORTED   (0x01 << 6)
#define	BLE_LNS_FEATURE_REMAINING_DISTANCE_SUPPORTED   (0x01 << 7)
#define	BLE_LNS_FEATURE_REMAINING_VERT_DISTANCE_SUPPORTED   (0x01 << 8)
#define	BLE_LNS_FEATURE_EST_TIME_OF_ARRIVAL_SUPPORTED   (0x01 << 9)
#define	BLE_LNS_FEATURE_NUM_SATS_IN_SOLUTION_SUPPORTED   (0x01 << 10)
#define	BLE_LNS_FEATURE_NUM_SATS_IN_VIEW_SUPPORTED   (0x01 << 11)
#define	BLE_LNS_FEATURE_TIME_TO_FIRST_FIX_SUPPORTED   (0x01 << 12)
#define	BLE_LNS_FEATURE_EST_HORZ_POS_ERROR_SUPPORTED   (0x01 << 13)
#define	BLE_LNS_FEATURE_EST_VERT_POS_ERROR_SUPPORTED   (0x01 << 14)
#define	BLE_LNS_FEATURE_HORZ_DILUTION_OF_PRECISION_SUPPORTED   (0x01 << 15)
#define	BLE_LNS_FEATURE_VERT_DILUTION_OF_PRECISION_SUPPORTED   (0x01 << 16)
#define	BLE_LNS_FEATURE_LOC_AND_SPEED_CONTENT_MASKING_SUPPORTED   (0x01 << 17)
#define	BLE_LNS_FEATURE_FIX_RATE_SETTING_SUPPORTED   (0x01 << 18)
#define	BLE_LNS_FEATURE_ELEVATION_SETTING_SUPPORTED   (0x01 << 19)
#define	BLE_LNS_FEATURE_POSITION_STATUS_SUPPORTED   (0x01 << 20)
#define	BLE_LNS_MAX_ROUTE_NAME_LEN   (BLE_L2CAP_MTU_DEF-5)
#define	BLE_LNS_MAX_NUM_ROUTES   3
#define	BLE_LNS_INVALID_ROUTE   0xFFFF
#define	BLE_LNS_NO_FIX   0xFF
#define	MAX_CTRL_POINT_RESP_PARAM_LEN   BLE_LNS_MAX_ROUTE_NAME_LEN + 3

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 *p_lns, ble_lns_evt_t *p_evt)
	Location and Navigation Service event handler type.
typedef struct ble_lns_routes_s	ble_lns_route_t
	Definition of a navigation route.

Enumerations
enum	ble_lns_ctrl_point_opcodes_t {   OP_CODE_RESERVED = 0x00,   OP_CODE_SET_CUMULATIVE_VALUE = 0x01,   OP_CODE_MASK_LOC_SPEED_CONTENT = 0x02,   OP_CODE_NAV_CONTROL = 0x03,   OP_CODE_REQ_NUM_ROUTES = 0x04,   OP_CODE_REQ_NAME_OF_ROUTE = 0x05,   OP_CODE_SELECT_ROUTE = 0x06,   OP_CODE_SET_FIX_RATE = 0x07,   OP_CODE_SET_ELEVATION = 0x08,   OP_CODE_RESPONSE_CODE = 0x20 }
enum	ble_lns_ctrl_point_response_codes_t {   CONTROL_POINT_RESP_RESERVED = 0x00,   CONTROL_POINT_RESP_SUCCESS = 0x01,   CONTROL_POINT_RESP_OP_CODE_NOT_SUPPORTED = 0x02,   CONTROL_POINT_RESP_INVALID_PARAMETER = 0x03,   CONTROL_POINT_RESP_OPERATION_FAILED = 0x04,   CONTROL_POINT_RESP_PROC_ALR_IN_PROG = BLE_GATT_STATUS_ATTERR_CPS_PROC_ALR_IN_PROG,   CONTROL_POINT_RESP_CCCD_CONFIG_IMPROPER = BLE_GATT_STATUS_ATTERR_CPS_CCCD_CONFIG_ERROR }
enum	ble_lns_evt_type_t {   BLE_LNS_LOC_SPEED_EVT_NOTIFICATION_ENABLED,   BLE_LNS_LOC_SPEED_EVT_NOTIFICATION_DISABLED,   BLE_LNS_LOC_SPEED_EVT_MASK_SET,   BLE_LNS_LOC_SPEED_EVT_TOTAL_DISTANCE_SET,   BLE_LNS_LOC_SPEED_EVT_ELEVATION_SET,   BLE_LNS_POS_QUAL_EVT_FIX_RATE_SET,   BLE_LNS_CONTROL_POINT_EVT_INDICATION_ENABLED,   BLE_LNS_CONTROL_POINT_EVT_INDICATION_DISABLED,   BLE_LNS_NAVIGATION_EVT_COMMAND,   BLE_LNS_NAVIGATION_EVT_ROUTE_SELECTED,   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_navigation_command_t {   BLE_LNS_NAVIGATION_STOP = 0x00,   BLE_LNS_NAVIGATION_START = 0x01,   BLE_LNS_NAVIGATION_PAUSE = 0x02,   BLE_LNS_NAVIGATION_CONTINUE = 0x03,   BLE_LNS_NAVIGATION_SKIP_WAYPOINT = 0x04,   BLE_LNS_NAVIGATION_NEAREST = 0x05 }
	Navigation commands. These commands can be sent to the control point and returned by an event callback. More...
enum	ble_lns_ctrlpt_procedure_status_t {   BLE_LNS_CTRLPT_STATE_NO_PROC_IN_PROGRESS,   BLE_LNS_CTRLPT_STATE_INDICATION_PENDING,   BLE_LNS_CTRLPT_STATE_IND_CONFIRM_PENDING }
	Location and Navigation Control Point procedure status (indicates if a procedure is in progress or not and which procedure is in progress). 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
uint32_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 *p_ble_evt)
	Function for handling Location and Navigation Service BLE stack events. More...
uint32_t	ble_lns_loc_speed_send (ble_lns_t *p_lns)
	Function for sending location and speed data if notification has been enabled. More...
uint32_t	ble_lns_navigation_send (ble_lns_t *p_lns)
	Function for sending navigation data if notification has been enabled. More...
uint32_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...
uint32_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.

Macro Definition Documentation

#define BLE_LNS_FEATURE_ELEVATION_SETTING_SUPPORTED   (0x01 << 19)

Elevation Setting Supported bit.

#define BLE_LNS_FEATURE_ELEVATION_SUPPORTED   (0x01 << 3)

Elevation Supported bit.

#define BLE_LNS_FEATURE_EST_HORZ_POS_ERROR_SUPPORTED   (0x01 << 13)

Estimated Horizontal Position Error Supported bit.

#define BLE_LNS_FEATURE_EST_TIME_OF_ARRIVAL_SUPPORTED   (0x01 << 9)

Estimated Time of Arrival Supported bit.

#define BLE_LNS_FEATURE_EST_VERT_POS_ERROR_SUPPORTED   (0x01 << 14)

Estimated Vertical Position Error Supported bit.

#define BLE_LNS_FEATURE_FIX_RATE_SETTING_SUPPORTED   (0x01 << 18)

Fix Rate Setting Supported bit.

#define BLE_LNS_FEATURE_HEADING_SUPPORTED   (0x01 << 4)

Heading Supported bit.

#define BLE_LNS_FEATURE_HORZ_DILUTION_OF_PRECISION_SUPPORTED   (0x01 << 15)

Horizontal Dilution of Precision Supported bit.

#define BLE_LNS_FEATURE_INSTANT_SPEED_SUPPORTED   (0x01 << 0)

Instaneous Speed Supported bit.

#define BLE_LNS_FEATURE_LOC_AND_SPEED_CONTENT_MASKING_SUPPORTED   (0x01 << 17)

Location and Speed Characteristic Content Masking Supported bit.

#define BLE_LNS_FEATURE_LOCATION_SUPPORTED   (0x01 << 2)

Location Supported bit.

#define BLE_LNS_FEATURE_NUM_SATS_IN_SOLUTION_SUPPORTED   (0x01 << 10)

Number of Satellites in Solution Supported bit.

#define BLE_LNS_FEATURE_NUM_SATS_IN_VIEW_SUPPORTED   (0x01 << 11)

Number of Satellites in View Supported bit.

#define BLE_LNS_FEATURE_POSITION_STATUS_SUPPORTED   (0x01 << 20)

Position Status Supported bit.

#define BLE_LNS_FEATURE_REMAINING_DISTANCE_SUPPORTED   (0x01 << 7)

Remaining Distance Supported bit.

#define BLE_LNS_FEATURE_REMAINING_VERT_DISTANCE_SUPPORTED   (0x01 << 8)

Remaining Vertical Distance Supported bit.

#define BLE_LNS_FEATURE_ROLLING_TIME_SUPPORTED   (0x01 << 5)

Rolling Time Supported bit.

#define BLE_LNS_FEATURE_TIME_TO_FIRST_FIX_SUPPORTED   (0x01 << 12)

Time to First Fix Supported bit.

#define BLE_LNS_FEATURE_TOTAL_DISTANCE_SUPPORTED   (0x01 << 1)

Total Distance Supported bit.

#define BLE_LNS_FEATURE_UTC_TIME_SUPPORTED   (0x01 << 6)

UTC Time Supported bit.

#define BLE_LNS_FEATURE_VERT_DILUTION_OF_PRECISION_SUPPORTED   (0x01 << 16)

Vertical Dilution of Precision Supported bit.

#define BLE_LNS_MAX_NUM_ROUTES   3

The maximum number of routes. This affects memory usage only.

#define BLE_LNS_MAX_ROUTE_NAME_LEN   (BLE_L2CAP_MTU_DEF-5)

The maximum length of length of a route name.

Enumeration Type Documentation

enum ble_lns_ctrl_point_opcodes_t

Enumerator
OP_CODE_RESERVED	Reserved for future use.
OP_CODE_SET_CUMULATIVE_VALUE	Set Cumulative Value.
OP_CODE_MASK_LOC_SPEED_CONTENT	Mask Location and Speed Characteristic Content.
OP_CODE_NAV_CONTROL	Navigation Control.
OP_CODE_REQ_NUM_ROUTES	Request Number of Routes.
OP_CODE_REQ_NAME_OF_ROUTE	Request Name of Route.
OP_CODE_SELECT_ROUTE	Select Route.
OP_CODE_SET_FIX_RATE	Set Fix Rate.
OP_CODE_SET_ELEVATION	Set Elevation.
OP_CODE_RESPONSE_CODE	Response code.

enum ble_lns_ctrl_point_response_codes_t

Enumerator
CONTROL_POINT_RESP_RESERVED	Reserved for future use.
CONTROL_POINT_RESP_SUCCESS	Success.
CONTROL_POINT_RESP_OP_CODE_NOT_SUPPORTED	Op Code not supported.
CONTROL_POINT_RESP_INVALID_PARAMETER	Invalid Parameter.
CONTROL_POINT_RESP_OPERATION_FAILED	Operation Failed.
CONTROL_POINT_RESP_PROC_ALR_IN_PROG	Control point procedure is already in progress.
CONTROL_POINT_RESP_CCCD_CONFIG_IMPROPER	CCCD is improperly configured.

enum ble_lns_ctrlpt_procedure_status_t

Location and Navigation Control Point procedure status (indicates if a procedure is in progress or not and which procedure is in progress).

Enumerator
BLE_LNS_CTRLPT_STATE_NO_PROC_IN_PROGRESS	No procedure in progress.
BLE_LNS_CTRLPT_STATE_INDICATION_PENDING	Control Point indication is pending.
BLE_LNS_CTRLPT_STATE_IND_CONFIRM_PENDING	Waiting for the indication confirmation.

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_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_LOC_SPEED_EVT_MASK_SET	Location and Speed feature mask was set.
BLE_LNS_LOC_SPEED_EVT_TOTAL_DISTANCE_SET	Location and Navigation total distance was set.
BLE_LNS_LOC_SPEED_EVT_ELEVATION_SET	Location and Navigation elevation was set.
BLE_LNS_POS_QUAL_EVT_FIX_RATE_SET	Fix rate was set.
BLE_LNS_CONTROL_POINT_EVT_INDICATION_ENABLED	Location and Navigation Control point indication was enabled.
BLE_LNS_CONTROL_POINT_EVT_INDICATION_DISABLED	Location and Navigation Control point indication was disabled.
BLE_LNS_NAVIGATION_EVT_COMMAND	A navigation command was issued.
BLE_LNS_NAVIGATION_EVT_ROUTE_SELECTED	A route was selected.
BLE_LNS_NAVIGATION_EVT_NOTIFICATION_ENABLED	Navigation value notification was enabled.
BLE_LNS_NAVIGATION_EVT_NOTIFICATION_DISABLED	Navigation value notification was disabled.

enum ble_lns_navigation_command_t

Navigation commands. These commands can be sent to the control point and returned by an event callback.

Enumerator
BLE_LNS_NAVIGATION_STOP	When received, is_navigation_running in ble_lns_s will be set to false.
BLE_LNS_NAVIGATION_START	When received, is_navigation_running in ble_lns_s will be set to true.
BLE_LNS_NAVIGATION_PAUSE	When received, is_navigation_running in ble_lns_s will be set to false.
BLE_LNS_NAVIGATION_CONTINUE	When received, is_navigation_running in ble_lns_s will be set to true.
BLE_LNS_NAVIGATION_SKIP_WAYPOINT	When received, is_navigation_running in ble_lns_s will not be affected.
BLE_LNS_NAVIGATION_NEAREST	When received, is_navigation_running in ble_lns_s will be set to true.

Function Documentation

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

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

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

Returns

Otherwise, an error code from sd_ble_gatts_hvx() is returned.

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

Returns

Otherwise, an error code from sd_ble_gatts_hvx() is returned.

void ble_lns_on_ble_evt	(	ble_lns_t *	p_lns,
		ble_evt_t *	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.

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