Sie sind auf Seite 1von 32

nanoLOC nTRX

Driver Suite
User Guide
Version 2.5
NA-07-0240-0407-2.5

Document Information
nanoLOC nTRX Driver Suite User Guide

Document Information
Document Title:

nanoLOC nTRX Driver Suite User Guide

Document Version:

2.5

Published (yyyy-mm-dd):

2010-03-31

Current Printing:

2010-3-30, 6:07 pm

Document ID:

NA-07-0240-0407-2.5

Document Status:

Released

Disclaimer
Nanotron Technologies GmbH believes the information contained herein
is correct and accurate at the time of release. Nanotron Technologies
GmbH reserves the right to make changes without further notice to the
product to improve reliability, function or design. Nanotron Technologies
GmbH does not assume any liability or responsibility arising out of this
product, as well as any application or circuits described herein, neither
does it convey any license under its patent rights.
As far as possible, significant changes to product specifications and
functionality will be provided in product specific Errata sheets, or in new
versions of this document. Customers are encouraged to check the Nanotron website for the most recent updates on products.

Page ii NA-07-0240-0407-2.5

Trademarks
All other trademarks, registered trademarks, and product names are the
sole property of their respective owners.
This document and the information contained herein is the subject of
copyright and intellectual property rights under international convention.
All rights reserved. No part of this document may be reproduced, stored
in a retrieval system, or transmitted in any form by any means, electronic, mechanical or optical, in whole or in part, without the prior written
permission of Nanotron
Technologies GmbH.
Copyright 2010 Nanotron Technologies GmbH.

2010 Nanotron Technologies GmbH.

Table of Contents
nanoLOC nTRX Driver Suite User Guide

Table of Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1
1.2
1.3
1.4

nanoLOC nTRX Driver Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


Modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Key Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example Implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1
1
2
2

2 nanoLOC API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1
2.2
2.3
2.4

nanoLOC nTRX Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3


General Layer Interface SAP, MESAP and Callback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
General Message Structure MsgT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Hardware Adaption Layer Microcontroller and Hardware Dependent . . . . . . . . . . . . . . . . . . . . . 5
2.4.1 SPI Bus Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4.2 Interrupt Service Routine Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.5 Chip Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.6 PHY Layer (nTRX Driver) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.6.1 PHY Layer Data SAP PDSap (). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.6.2 PHY Layer Management Entity SAP PLMESap () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.6.3 Upstream Callback Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.7 Application Layer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.7.1 Using PDSap () on the PHY Layer for Data Transmission Requests. . . . . . . . . . . . . . . . . . . 7
2.7.2 Using PLMESap () on the PHY Layer Chip Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.7.3 Upstream Callback Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3 nanoLOC Ranging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.1 Symmetrical Double Sided Two-Way Ranging (SDS-TWR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.1 SDS-TWR Defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.2 Propagation and Processing Delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.3 Generating First Set of Time Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.4 Granting Permission to Perform Measurements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.5 Eliminating Clock Errors by a Second Symmetrical Measurement . . . . . . . . . . . . . . . . . . .
3.1.6 Collecting the Time Values with a Third Data Packet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.7 Calculating the Ranging Distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Ranging Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.1 SDS-TWR 3W_A Providing Ranging Results to Peer A . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.2 SDS-TWR 3W_B Providing Ranging Results to Peer B . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.3 SDS-TWR 2W_PP Energy Saving Ranging Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3 Success and Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.1 Success Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.2 Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11
11
11
12
12
12
12
13
14
14
16
17
19
19
20

4 Driver Demo Hardware Access/Interface Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21


4.1 appl.c Module User Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1.2 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2 hwclock.c Module Timer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3 usart.c Serial Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.2 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4 nnspi.c Module SPI Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.2 Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5 main.c Module Main Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.2 Starting Up and Running an Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.3 Initializing the nanoLOC TRX Transceiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.4 Setting Up the User Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.5 The Main Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2010 Nanotron Technologies GmbH.

21
21
21
21
21
22
22
22
22
22
22
23
23
23
23
23
23

NA-07-0240-0407-2.5 Page iii

Table of Contents
nanoLOC nTRX Driver Suite User Guide

4.5.6 Transmitting Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24


4.5.7 Receiving Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Page iv NA-07-0240-0407-2.5

2010 Nanotron Technologies GmbH.

Introduction
nanoLOC nTRX Driver Suite User Guide

1 Introduction
This document describes the structure of the nanoLOC nTRX Driver model as well as the interface
the driver provides for accessing the nanoLOC TRX Transceiver. Additionally, a description of the
nTRX Driver Demo is provided. This software is a complete sample application for the nanoLOC
DK Board that is can be compiled and downloaded to the board for evaluation purposes.

1.1

nanoLOC nTRX Driver Overview


Wireless applications that access the nanoLOC chip do so through the API of the nanoLOC nTRX
Driver. Upper layers, including the application layer, communicate with lower layers by sending and
receiving messages. This API allows the application layer to access the chips functions including
chip-specific settings and performance criteria such as address matching, error checking, modulation methods, and data transmission rates. Furthermore, hardware adaption layer messages are
sent to the nanoLOC chip over the SPI interface. The nanoLOC API is located within the phy.c
module of the nanoLOC nTRX Driver source code.

1.2

Modules
The nanoLOC nTRX Driver consists of the following four modules:
+

ntrxinit.c
This module contains the initialization function for the nanoLOC chip.

ntrxiqpar.c
This module contains the chirp sequence values for the chirp sequencer in the nanoLOC chip.

phy.c
This module contains the nanoLOC nTRX Driver API and is used for transmitting and receiving
messages.

ntrxutil.c
This module contains the utility functions needed by other nanoLOC nTRX Driver modules for
calibration and general register access.

ntrxranging.c
This module contains the implementation of the nanoLOC nTRX Driver ranging functions.

The following figure shows the relationship between these four modules:
phy.c
Data I/O
ntrxinit.c

ntrxiqpar.c

nanoLOC chip Initialization

RF Modes
functions

ntrxutil.c
Calibr. fn
Generic fn

ranging.c
Ranging functions

Figure 1: nanoLOC nTRX Driver modules

2010 Nanotron Technologies GmbH.

NA-07-0240-0407-2.5 Page 1

Introduction

1.3

Key Settings

nanoLOC nTRX Driver Suite User Guide

Some of the key settings of the nanoLOC nTRX Driver include:

1.4

A means for the transceiver to access upper layers

Read and write values into transceiver registers

Set the Logical Network ID (which sets the SyncWord)

Enable/disable address matching

Enable/disable Broadcast (Brdcast) or Time Beacon (TimeB) packets

Enable/disable receiver CRC2 checking

Set CRC2 method to detect transmission bit errors

Set CSMA/CA (carrier sense method for collision avoidance)

Enable/disable a backoff scheme for packet collision avoidance

Enable/disable Automatic Repeat Request (ARQ) on the receiver

Set the transmission output power

Calibrate frequency of transmission and reception oscillators

Set frequency bandwidth

Select frequency channel (for narrowband transmission)

Read out range (distance) value

Manually start and stop packet transmission

Set data transmission rate

Enable/disable FEC

Example Implementation
Figure 2 below shows an example implementation of the nanoLOC nTRX Driver.
= Interface
Application Layer

Logical Connection

TX

= Message

Application Layer

RX

PHY Layer (nTRX Driver)

PHY Layer (nTRX Driver)

Event Handler

Event Handler

Hardware Adaption
Layer

Hardware Adaption
Layer

nanoLOC
Chip

nanoLOC
Chip
Physical Connection

Transmitted Packet

TX

RX

Received Packet

Figure 2: Example nanoLOC TRX Driver implementation

Page 2 NA-07-0240-0407-2.5

2010 Nanotron Technologies GmbH.

nanoLOC API
nanoLOC nTRX Driver Suite User Guide

2 nanoLOC API
This section describes how an application accesses chip functionality through the use of the application programming interface (API) of the nanoLOC nTRX Driver. The API uses the same naming
convention as IEEE 802.15.4.

2.1

nanoLOC nTRX Driver


Applications access the nanoLOC TRX Transceiver through the API of the nanoLOC nTRX Driver.
Upper layers, including the application layer, communicate with lower layers by sending and
receiving commands. With this API, the application layer has a simple means of accessing the
chips functions, including chip-specific settings and performance criteria such as address matching, error checking, modulation methods, and data transmission rates. Hardware adaption layer
messages are sent to the nanoLOC chip over the SPI interface. The nanoLOC API is located
within the phy.c module of the nTRX Driver source code.
= Interface

Logical Connection

Application Layer

TX

= Message

Application Layer

RX

= SAP
PHY Layer (nTRX Driver)

PHY Layer (nTRX Driver)

Event Handler

Event Handler

Hardware Adaption
Layer

Hardware Adaption
Layer

nanoLOC
TRX Transceiver

nanoLOC
TRX Transceiver
Physical Connection

Transmitted Packet

TX

RX

Received Packet

Figure 3: Layer structure

The nanoLOC TRX Driver API reads and writes values into the registers of the nanoLOC TRX
Transceiver. Some of the key settings of the nanoLOC TRX Driver include the following:
+

Sets the Logical Network ID (which sets the


SyncWord)

Enables / disables address matching

Enables / disables Broadcast (Brdcast) or


Time Beacon (TimeB) packets

Enables / disables receiver CRC2 checking

Sets CRC2 method to detect transmission


bit errors

Sets CSMA/CA (carrier sense method for


collision avoidance)

Enables / disables a backoff scheme for


packet collision avoidance

Enables / disables Automatic


Request (ARQ) on the receiver

2010 Nanotron Technologies GmbH.

Sets the transmission output power

Calibrates frequency of transmission and


reception oscillators

Sets frequency bandwidth

Selects frequency channel (for narrowband


transmission)

Reads out range (distance) value

Manual starting and stopping packet transmission

Sets the data transmission rate

Enables / disables Forward Error Correction


(FEC)

Repeat

NA-07-0240-0407-2.5 Page 3

2
2.2

nanoLOC API
nanoLOC nTRX Driver Suite User Guide

General Layer Interface SAP, MESAP and Callback


All communication between layers is done by sending and receiving messages. Each layer has the
same interface and can be easily exchanged or extended without changing the overall interface.
Service Access Points (SAPs) are implemented as C functions and accepts a single pointer to a
C-Struct interpreted as a message. This message contains all the necessary information required
to execute a task from an upper layer. Figure 4 below illustrates the general layer interface (SAP,
MESAP and Callback) of the nanoLOC nTRX Driver.
Application Layer
APPCallback

PDSap

PLMESap
PHY layer (nTRX Driver)

C and HW independent

PDCallback

Hardware Adaption Layer

SPI Interface

IRQ

C and HW dependent

Reset

nanoLOC Chip
Figure 4: nTRX Driver API General layer interface

The PHY layer provides two Service Access Points (SAPs) for downstream messages from the
Application Layer: LayernameSAP and LayernameMESAP. The PHY layer also provides one callback function for upstream messages from the Hardware Adaption Layer: LayernameCallback.
The general form for these SAPs are:
+

Downstream SAPs:
void LayernameSAP (MsgT *msg);
void LayernameMESAP (MsgT *msg);

On the PHY layer, these SAPs are:


void PDSap (MsgT *msg)
void PLMESap (MsgT *msg)
+

Upstream Callback Function:


void LayernameCallback (MsgT *msg);

On the PHY layer, this callback function is:


void PDCallback (void)
+

In addition to these services, every layer has variables that have to be initialized. This action is
put into a separate function called LayernameInit:
void LayernameInit (void);

On the PHY layer, this function is:


void PHYInit (void)

Page 4 NA-07-0240-0407-2.5

2010 Nanotron Technologies GmbH.

nanoLOC API
nanoLOC nTRX Driver Suite User Guide

2.3

General Message Structure MsgT


For a layer to provide information to a lower layer, the message structure MsgT is used, which is
located in the file ntrxtypes.h. Return values are also provided with the help of this structure.
typedef struct
{
uint8_t prim;
AddrT addr;
uint8_t len;
uint8_t *pdu;
uint8_t data[CONFIG_MAX_PACKET_SIZE];
uint8_t status;
uint16_t value;
uint8_t attribute;
} MsgT;

The primitive of the message.


MAC address of the message.
Payload length
pointer to beginning of payload in buffer
Payload of the message
Status value for confirmations
Configuration value of a layer setting
Attribute for setting or getting chip configuration requests

Figure 5: MsgT message structure

Table 1 below describes the variables in the message structure MsgT.


Table 1: Description of MsgT Message structure

2.4

Variable

Description

uint8_t prim;

Primitive name (1 byte)

AddrT addr;

MAC address of destination station (6 bytes)

uint8_t len;

Length of message (1 byte)

uint8_t *pdu;

Points to the beginning of the payload in the buffer

uint8_t
data[MAX_PACKET_SIZE];

Payload of message (n bytes to a maximum of 128 bytes)

uint8_t status;

Status indicator used with LayerCallback function (1 byte)

uint16_t value;

Value of requested parameter used for setting or getting chip configuration requests (2 bytes)

uint8_t attribute;

Selected attribute used with the value parameter for setting or getting chip configuration requests (1 byte)

Hardware Adaption Layer Microcontroller and Hardware Dependent


The Hardware Adaption Layer is used to access the nanoLOC TRX Transceiver and |is dependent
on the microcontroller and hardware.
PDCallback

Hardware Adaption Layer

SPI Interface

IRQ

Reset

nanoLOC Chip

Figure 6: Hardware adaption layer

Note: This layer must be written for each microcontroller family. The nanoLOC Development Kit
uses the Atmel ATmega128L microcontroller, which is part of the AVR family of microcontrollers.
2010 Nanotron Technologies GmbH.

NA-07-0240-0407-2.5 Page 5

nanoLOC API
nanoLOC nTRX Driver Suite User Guide

2.4.1 SPI Bus Functions


The implementation of the Hardware Adaption Layer for AVR microcontrollers uses four functions
to communicate with the nanoLOC chip over the SPI bus. It also uses an interrupt service routine.
The functions for the SPI bus include:
void
void
void
void

NTRXSPIRead(uint8_t address, uint8_t *buffer, uint8_t len);


NTRXSPIWrite(uint8_t address, uint8_t *buffer, uint8_t len);
NTRXSPIReadByte(uint8_t address, uint8_t *buffer);
NTRXSPIWriteByte(uint8_t address, uint8_t buffer);

where:
+

NTRXSPIRead reads multiple bytes to the nanoLOC chip

NTRXSPIWrite writes multiple bytes to the nanoLOC chip

NTRXSPIReadByte reads single bytes to the nanoLOC chip

NTRXSPIWriteByte writes single bytes to the nanoLOC chip

2.4.2 Interrupt Service Routine Function


The function used for interrupt service routines is:
void NTRXInterrupt (void)

The interrupt service routine will read the IRQ status register and raise a flag for transmission finished or message reception. The actual processing of the interrupt source is done in normal context through the use of the function PHYPoll().

2.5

Chip Initialization
To prepare the nanoLOC chip for message sending and receiving, the following function is used:
bool_t NtrxInit(void)

2.6

PHY Layer (nTRX Driver)


The PHY layer provides two downstream SAPs for the Application Layer and an upstream callback
function for the Hardware Adapter Layer, as shown in figure 7 below.
Application Layer
APPCallback

PDSap

PLMESap
PHY layer (nTRX Driver)
PDCallback

Hardware Adaption Layer


Figure 7: PHY layer SAPS

Page 6 NA-07-0240-0407-2.5

2010 Nanotron Technologies GmbH.

nanoLOC API
nanoLOC nTRX Driver Suite User Guide

2.6.1 PHY Layer Data SAP PDSap ()


PDSap () is used by the Application Layer for downstream data transmission to the PHY layer.
This SAP uses the message structure MsgT.
void PDSap (MsgT *msg)

For details on the structure MsgT and parameters required for the SAP PDSap (), see 2.7.1. Using
PDSap () on the PHY Layer for Data Transmission Requests on page 7:
2.6.2 PHY Layer Management Entity SAP PLMESap ()
PLMESap() is used by the Application Layer for nanoLOC chip configuration requests and queries.
void PLMESap (MsgT *msg)

For details on the structure MsgT and parameters required for the SAP PLMESap (), see 2.7.2.
Using PLMESap () on the PHY Layer Chip Configuration on page 8:
2.6.3 Upstream Callback Function
The PHY layer provides a single upstream Callback function PDCallback.
void PDCallback (void)

2.7

Application Layer
The Application Layer accesses the two downstream SAPs on the PHY layer PDSap () and
PLMESap ()and provides to the PHY layer an upstream callback function, as shown in figure 8
below:
Application Layer
APPCallback

PDSap

PLMESap
PHY layer (nTRX Driver)
Figure 8: Application layer

2.7.1 Using PDSap () on the PHY Layer for Data Transmission Requests
The Application layer uses the PHY layer SAP PDSap () for data transmission.
void PDSap (MsgT * msg)

The Application layer uses MsgT, as described in section 2.3 (unused parameters noted below).
typedef struct
{
uint8_t prim;
AddrT addr;
uint8_t len;
uint8_t *pdu;
uint8_t data[128];
uint8_t status;
uint16_t value;
uint8_t attribute;
} MsgT;

2010 Nanotron Technologies GmbH.

Not used for sending messages

NA-07-0240-0407-2.5 Page 7

nanoLOC API
nanoLOC nTRX Driver Suite User Guide

Primitives
The parameter prim uses the following primitives (attribute parameter) to indicate the requested
service:
+

PD_DATA_CONFIRM Hardware acknowledgement has been received


PURPOSE: Indicates that a PD_DATA_REQUEST message was successfully executed.
Valid parameters include data payload (data), destination address (addr), payload length
(len), and success or failure (status).

PD_DATA_INDICATION Message has been received


PURPOSE: A message has been received from another device.
Valid parameters are data payload (data), source address (addr), and payload length (len).

PD_DATA_REQUEST Transmit a message


PURPOSE: Requests a message to be transmitted to a given destination.
Valid parameters include type of request (prim), destination address (addr), data payload
(data), and payload length (len).

2.7.2 Using PLMESap () on the PHY Layer Chip Configuration


The Application layer sends configuration requests and queries to the nanoLOC TRX Transceiver
using the SAP PLMESap() on the PHY Layer.
void PLMESap (MsgT * msg)

The Application layer uses MsgT, as described in section 2.3 (unused parameters noted below).
typedef struct
{
uint8_t prim;
AddrT addr;
Not used
uint8_t len;
uint8_t *pdu;
uint8_t data[128];
uint8_t status;
uint16_t value;
uint8_t attribute;
} MsgT;

Primitives
The parameter prim uses the following primitives (attribute parameter) to indicate the requested
service:
+

PLME_GET_REQUEST
PURPOSE: Queries a setting of the layer parameter. For example, is FEC set to on?
The attribute parameter is used to select one of the supported attributes (see below), while
the value parameter selects the current setting of the attribute. The value field is only valid if
the status field indicates no error.

PLME_SET_REQUEST
PURPOSE: Sets a parameter of the layer. For example, set FEC to on.
The attribute parameter is used to select one of the supported attributes (see below), while
the value parameter provides the new value to set.

Page 8 NA-07-0240-0407-2.5

2010 Nanotron Technologies GmbH.

nanoLOC API
nanoLOC nTRX Driver Suite User Guide

Attributes
The following attributes are available to be set or queried through the function PLMESap().
+

PHY_LOG_CHANNEL
PURPOSE: Selects or requests a logical channel, which is a predefined set of transmission
mode settings. Table 2 lists the supported logical channels.
Table 2: NTRX_LogChannel attributes

Logical Channel

Bandwidth [MHz]

Bitrate [ns]

FEC

Centerfreq ID

NLC_80_1_N_0

80

1000

No

NLC_22_4_N_1

22

4000

No

NLC_22_4_N_7

22

4000

No

NLC_22_4_N_13

22

4000

No

13

PHY_CHANNEL
PURPOSE: Sets the center frequency used in the NTRX_Mode. Table 3 lists the available channels:
Table 3: NTRX_Channel attributes

Channel ID

Center Frequency [GHz]

Description

2.442.175

CSS, 80 MHz

2.412

802.11b, CHNL_ID 1

2.417

802.11b, CHNL_ID 2

2.422

802.11b, CHNL_ID 3

2.427

802.11b, CHNL_ID 4

2.432

802.11b, CHNL_ID 5

2.437

802.11b, CHNL_ID 6

2.442

802.11b, CHNL_ID 7

2.447

802.11b, CHNL_ID 8

2.452

802.11b, CHNL_ID 9

10

2.457

802.11b, CHNL_ID 10

11

2.462

802.11b, CHNL_ID 11

12

2.467

802.11b, CHNL_ID 12

13

2.472

802.11b, CHNL_ID 13

14

2.484

802.11b, CHNL_ID 14 (Japan)

15

2412.75

HR low band center frequency

16

2470.76

HR high band center frequency

PHY_ARQ
PURPOSE: Turns on and off automatic retransmissions. When on, it also sets the maximum
number of retransmissions. The range for maximum retransmissions is 0 to 14.

PHY_FEC
PURPOSE: This attribute turns on and off Forward Error Correction (FEC). For more details
about FEC, see nanoLOC TRX (NA5TR1) Transceiver User Guide.

PHY_TX_POWER
PURPOSE: This attribute sets the output power of the transmitter. The programmable output
power of the nanoLOC chip is from -33 dBm to 0 dBm.

2010 Nanotron Technologies GmbH.

NA-07-0240-0407-2.5 Page 9

nanoLOC API
nanoLOC nTRX Driver Suite User Guide

PHY_ADDR_MATCHING
PURPOSE: This attribute turns on and off address matching. For more details about address
matching, see nanoLOC TRX (NA5TR1) Transceiver User Guide.

NTRX_RTC
PURPOSE: This attribute accesses the Real Time Clock of the nanoLOC chip. For more details
about the Real Time Clock, see nanoLOC TRX (NA5TR1) Transceiver User Guide.

PHY_PWR_DOWN_MODE
PURPOSE: This attribute is used to put the nanoLOC chip into PowerDownModeFull or PowerDownModePad. For more details about power down modes, see nanoLOC TRX (NA5TR1)
Transceiver User Guide.

PHY_RECALIBRATION
PURPOSE: This attribute is used to switch cyclic recalibration on or off. In case of on, it also sets
the calibration interval. For more details about recalibration, see nanoLOC TRX (NA5TR1)
Transceiver User Guide.

PHY_MAC_ADDRESS1
PURPOSE: This attribute is used to set the local MAC address. This address is used for address
matching and as sender address when transmitting messages. For more details address
matching, see nanoLOC TRX (NA5TR1) Transceiver User Guide.

2.7.3 Upstream Callback Function


The Application Layer provides to the PHY layer the following upstream callback function:
void APPCallback (MsgT *msg)

Page 10 NA-07-0240-0407-2.5

2010 Nanotron Technologies GmbH.

nanoLOC Ranging
nanoLOC nTRX Driver Suite User Guide

3 nanoLOC Ranging
nanoLOC Ranging uses a methodology called Symmetrical Double-Sided Two-Way Ranging
(SDS-TWR) developed by Nanotron Technologies and is part of the nanoLOC nTRX Driver. In the
nanoLOC Development Kit three different ranging modes are available:

3.1

SDS-TWR 3W_A provides measurement results to Peer station A (the local station that
requested the ranging)

SDS-TWR 3W_B provides measurement results to Peer station B (the remote station with
which the location station is performing ranging)

SDS-TWR 2W_PP operates identical to 3W_A except it uses time data from the previous ranging request to reduce energy consumption and quicker generation of ranging results

Symmetrical Double Sided Two-Way Ranging (SDS-TWR)


3.1.1 SDS-TWR Defined
The SDS-TWR ranging methodology is:
+

Symmetrical as the first ranging measurement from Peer A to Peer B is mirrored by a second
ranging measurement from Peer B to Peer A

Double-Sided as the ranging measurement is performed between two peer nanoLOC - enabled
devices

Two-Way as a Data packet and an automatic hardware acknowledgement provide the time values used for determining the ranging measurement

Figure 9 below shows a SDS-TWR ranging request cycle with two-way (Data and Ack packet),
double-sided (Peer A and Peer B), and symmetrical (ABA and BAB) ranging.
Data packet

A to B to A
Ack packet

Peer A

Peer B

Data packet

B to A to B
Ack packet

Peer A

Peer B

Figure 9: SDS-TWR (simplified)

3.1.2 Propagation and Processing Delay


Key to SDS-TWR are two time delay values:
+

TX Propagation Delay, which is the time required for a speed of a signal propagating through
the air is known (speed of light), as is the time when the packet was sent and the time when it
was received. Using the delay and speed of light, a distance value can be generated.

Processing Delay
The nanoLOC TRX Transceiver uses a measured time delay to receive a data packet and to
generate and transmit a hardware acknowledgement packet.

2010 Nanotron Technologies GmbH.

NA-07-0240-0407-2.5 Page 11

nanoLOC Ranging
nanoLOC nTRX Driver Suite User Guide

3.1.3 Generating First Set of Time Values


The round trip of a Data packet and a hardware acknowledgement (Ack packet) is used to generate the TX propagation delay value T1, while the processing delay time is the value T2. This first
set of generated time values are shown in figure 10 below.
+

Generating T1
When the application on Peer A requests ranging, a Data packet is sent to Peer B which automatically returns an Ack packet. Peer A generates T1 using the time when the Data packet was
sent, when the Ack packet was received, and the known value of the signal propagation speed.
This value T1 is stored in memory on Peer A.

Generating T2
T2 is the measured value of processing an Ack packet in the nanoLOC TRX Transceiver. This
value T2 is stored in memory on Peer B.
Peer A
T1

Peer B
TX propagation delay - A to B to A

T2

Processing
delay

Figure 10: First set of measurements

3.1.4 Granting Permission to Perform Measurements


Once a request for ranging is sent to Peer B, this station needs to grant permission to perform the
ranging measurements before the remaining time values are generated. This allows a station to
temporarily suspend ranging measurements independent of the ranging request from the peer station. This permission is set in software and is read out by the peer station before the time values T2
and T3 are provided.
3.1.5 Eliminating Clock Errors by a Second Symmetrical Measurement
To eliminate any errors caused by the clock crystals on each peer station not being synchronized,
the ranging measurements are repeated symmetrically from Peer B to Peer A, as shown in figure
11 below. This generates a second set of time values T3 and T4.
+

Generating T3
After Peer B grants permission to continue with ranging, Peer B sends a Data packet to Peer A
which automatically returns an Ack packet. Peer B generates T3 using the time when the Data
packet was sent, when the Ack packet was received, and the known value of the signal propagation speed. This value T3 is stored in memory on Peer B.

Generating T4
T4 is the measured value of processing an Ack packet in the nanoLOC TRX Transceiver. This
value T4 is stored in memory on Peer A.
Peer A
T1

Peer B
TX propagation delay - A to B to A

Peer A
Processing
delay

T4

T2

Processing
delay

Peer B
TX propagation delay - B to A to B

T3

Figure 11: Second set of measurements

3.1.6 Collecting the Time Values with a Third Data Packet


When the ranging measurements have been completed, the time values need to be collected to
generate a ranging distance. Two values T1 and T4 are on Peer A while T2 and T3 are on Peer B.
nanoLOC Ranging provides several methods of collecting these values to provide flexibility for
designing ranging products.
Page 12 NA-07-0240-0407-2.5

2010 Nanotron Technologies GmbH.

nanoLOC Ranging
nanoLOC nTRX Driver Suite User Guide

SDS-TWR 3W_A uses Peer A to generate the ranging distance. This requires a third packet to
provide Peer B time values to Peer A, as shown in figure 12 below.
Peer A

Peer B
TX propagation delay - A to B to A

T1

T2

Peer A

Peer B
TX propagation delay - B to A to B

T4

T3

Peer A

Peer B
T2 and T3 provided to Peer A

Figure 12: Third Data packet to provide Peer B time values to Peer A

SDS-TWR 3W_B provides Peer A time values to Peer B, as shown in figure 13 below.
Peer A

Peer B
TX propagation delay - A to B to A

T1

T2

Peer A

Peer B
TX propagation delay - B to A to B

T4

T3

Peer A

Peer B
T1 and T4 provided to Peer B

Figure 13: Third Data packet to provide Peer A time values to Peer B

SDS-TWR 2W_PP uses time values from a previous ranging request to generate the ranging
distance.

T1 and T4 from
previous ranging
request provided
to Peer A

Peer A

Peer B
TX propagation delay - A to B to A

T1

T2

Peer A

Peer B
TX propagation delay - B to A to B

T4

T3

T2 and T4 for
next ranging
ranging

Peer B
Figure 14: Third Data packet not required

These methods are described in detail in 3.2. Ranging Modes on page 14.
3.1.7 Calculating the Ranging Distance
With all four time values available, the distance between Peer A and Peer B can be generated
using the following formula:

( T1 T2 ) + ( T3 T4 )

Distance = -------------------------------

where:
T1 - T2 = measurement 1
T1 = TX Propagation delay time of a round trip between Peer A and Peer B
T2 = Processing delay in Peer B
T3 - T4 = measurement 2
T3 = TX Propagation delay time of a round trip between Peer B and Peer A
T4 = Processing delay in Peer A
2010 Nanotron Technologies GmbH.

NA-07-0240-0407-2.5 Page 13

3
3.2

nanoLOC Ranging
nanoLOC nTRX Driver Suite User Guide

Ranging Modes
Three ranging modes are provided to allow flexible development of ranging and location-aware
applications: 3W_A, 3W_B, and 2W_PP.
3.2.1 SDS-TWR 3W_A Providing Ranging Results to Peer A
In this mode, Peer A generates the ranging distance. Data can be included in payload. Permission
to perform measurements can be denied.
1

Peer A requests 3W_A ranging mode. User data can also be sent to Peer B, but will not be
read out after the ranging measurements have been completed.
void PDSap (MsgT *msg)

where the message structure is:

Variable

Description

uint8_t prim;

PD_RANGING_REQUEST

AddrT addr;

MAC address of destination address which is the ranging target.

uint8_t data[];

User data to be transmitted.

uint8_t len;

Length of user data with a maximum of 100 bytes.

uint8_t attribute;

RANGING_TYPE_3W_A

After sending the ranging request, Peer A receives a ranging confirmation.


void APLCallback (MsgT *msg)

where the message structure is:

Variable

Description

uint8_t prim;

PD_RANGING_CONFIRM

uint8_t status;

Status messages include PHY_SUCCESS (ranging has successfully


started), PHY_NO_ACK (remote station does not exist), and so on.

Peer B must grant permission for ranging to continue. User data can also be sent to Peer A at
this point.
bool_t Permission(uint8_t *macAddr, uint8_t *data, uint8_t *len)

where the parameters are:


Parameter

Description

AddrT *macAddr

Address of the requesting ranging station (Peer A)

uint8_t *data

A pointer to user data with a maximum of 100 bytes grants permission to ranging. To deny the ranging request, a null value must be
set.

uint8_t *len

Length of the user data.

Note: Permission code must be written as efficiently as possible to prevent Peer A station
from excessive waiting for the Data packet from Peer B. Otherwise, Peer A may switch
into sleep mode after a timeout.
Page 14 NA-07-0240-0407-2.5

2010 Nanotron Technologies GmbH.

nanoLOC Ranging
nanoLOC nTRX Driver Suite User Guide

If Peer B has put user data in the Data packet, a data indication is provided to Peer A.
void APLCallback (MsgT *msg)

where the message structure is:

Variable

Description

uint8_t prim;

PD_DATA_INDICATION

AddrT addr;

Source address of the Data packet.

uint8_t data[];

User data to be transmitted.

uint8_t len;

Length of user data with a maximum of 100 bytes.

Peer B transmits a second Data packet containing time values T2 and T3 to Peer A. When
Peer A receives this packet, it performs the distance measurement calculations using the four
accumulated time values T1, T2, T3, and T4. The resulting measurement is provides to an
application on Peer A via a ranging Indication.
void APLCallback (MsgT *msg)

where the message structure is:


Variable

Description

uint8_t prim;

PD_RANGING_INDICATION

AddrT addr;

Address of the remote station (Peer B).

uint8_t data[];

Data includes RangingMsgT structure.

uint8_t len;

Length of user data with a maximum of 100 bytes.

The RangingMsgT message structure is:


Variable

Description

uint8_t error;

Error status message1.

double distance;

Distance in meters between the peer stations.

AddrT addr;

Address of the remote station.

1.

See <Emphasis Footnote>Success and Error Messages on page 19

If Peer A has sent user data to Peer B during the ranging request, it is now provided to the
application.
void APLCallback (MsgT *msg)

where the message structure is:


Variable

Description

uint8_t prim;

PD_DATA_INDICATION

AddrT addr;

Source address of the Data packet.

uint8_t data[];

User data to be transmitted.

uint8_t len;

Length of user data with a maximum of 100 bytes.

2010 Nanotron Technologies GmbH.

NA-07-0240-0407-2.5 Page 15

nanoLOC Ranging
nanoLOC nTRX Driver Suite User Guide

3.2.2 SDS-TWR 3W_B Providing Ranging Results to Peer B


In this mode, Peer B generates the ranging distance. Data can be included in payload. Permission
to perform measurements can be denied.
1

Peer A requests 3W_B ranging mode:


void PDSap (MsgT *msg)

where the message structure is:

Variable

Description

uint8_t prim;

PD_RANGING_REQUEST

AddrT addr;

MAC address of destination address which is the ranging target.

uint8_t data[];

User data to be transmitted.

uint8_t len;

Length of user data with a maximum of 100 bytes.

uint8_t attribute;

RANGING_TYPE_3W_B

After sending the ranging request, Peer A receives a ranging confirmation.


void APLCallback (MsgT *msg)

where the message structure is:

Variable

Description

uint8_t prim;

PD_RANGING_CONFIRM

uint8_t status;

Status messages include PHY_SUCCESS (ranging has successfully


started), PHY_NO_ACK (remote station does not exist), and so on.

Peer B must grant permission for ranging to continue. User data can be added to the Data
packet at this point.
bool_t Permission(uint8_t *macAddr, uint8_t *data, uint8_t *len)

where the parameters are:

Parameter

Description

uint8_t *macAddr

Address of the requesting ranging station (Peer A)

uint8_t *data

To deny the ranging request, a null value must be set; a pointer to


user data with a maximum of 100 bytes grants permission to ranging.

uint8_t *len

Length of the user data.

If Peer A has sent user data to Peer B during the ranging request, it is now provided to the
application.
void APLCallback (MsgT *msg)

where the message structure is:


Variable

Description

uint8_t prim;

PD_DATA_INDICATION

AddrT addr;

Source address of the Data packet.

uint8_t data[];

User data to be transmitted.

uint8_t len;

Length of user data with a maximum of 100 bytes.

Page 16 NA-07-0240-0407-2.5

2010 Nanotron Technologies GmbH.

nanoLOC Ranging
nanoLOC nTRX Driver Suite User Guide

Peer A transmits a second Data packet containing time values T1 and T4 to Peer B. When
Peer B receives this packet, it performs the distance measurement calculations using the four
accumulated time values T1, T2, T3, and T4. The resulting measurement is provides to an
application on Peer B via a ranging Indication.
void APLCallback (MsgT *msg)

where the message structure is:


Variable

Description

uint8_t prim;

PD_RANGING_INDICATION

AddrT addr;

Address of the remote station (Peer B).

uint8_t data[];

Data includes RangingMsgT structure.

uint8_t len;

Length of user data with a maximum of 100 bytes.

The RangingMsgT message structure is:


Variable

Description

uint8_t error;

Error status message1.

double distance;

Distance in meters between the peer stations.

AddrT addr;

Address of the remote station.

1.

See <Emphasis Footnote>Success and Error Messages on page 19.

If Peer B has put user data in the Data packet when it granted permission to perform ranging, a
data indication is now provided to Peer A.
APLCallback (MsgT *msg)

where the message structure is:


Variable

Description

uint8_t prim;

PD_DATA_INDICATION

AddrT addr;

Source address of the Data packet.

uint8_t data[];

User data to be transmitted.

uint8_t len;

Length of user data with a maximum of 100 bytes.

3.2.3 SDS-TWR 2W_PP Energy Saving Ranging Mode


In this mode, the four time values T1, T2, T3, and T4 are provided by the immediate past ranging
request to quickly generate a distance measurement between Peer A and Peer B. The time values
obtained during the current SDS-TWR ranging request are stored and saved for the next ranging
request. Data can be included in payload. Permission to perform measurements can be denied.
1

Peer A requests 2W_PP ranging mode. User data can be sent to Peer B also, but will not be
read out after the ranging measurements have been completed. All time values (T1, T2, T3,
and T4) are provided by the previous ranging measurements.
void PDSap (MsgT *msg)

where the message structure is:


Variable

Description

uint8_t prim;

PD_RANGING_REQUEST

2010 Nanotron Technologies GmbH.

NA-07-0240-0407-2.5 Page 17

nanoLOC Ranging
nanoLOC nTRX Driver Suite User Guide

Variable

Description

AddrT addr;

MAC address of destination address which is the ranging target.

uint8_t data[];

User data to be transmitted.

uint8_t len;

Length of user data with a maximum of 100 bytes.

uint8_t attribute;

RANGING_TYPE_2W_PP

After sending the ranging request, Peer A will receive a ranging confirmation.
void APLCallback (MsgT *msg)

where the message structure is:


Variable

Description

uint8_t prim;

PD_RANGING_CONFIRM

uint8_t status;

Status messages include PHY_SUCCESS (ranging has successfully


started), PHY_NO_ACK (remote station does not exist)1.

1.

See <Emphasis Footnote>Success and Error Messages on page 19

Peer A now performs the ranging calculations using the accumulated time values T1, T2, T3,
and T4 from the previous ranging cycle. The results, however, are not provided to an application until a later step.

Peer B must grant permission for ranging to continue. User data can be added to the Data
packet at this point.
bool_t Permission(uint8_t *macAddr, uint8_t *data, uint8_t *len)

where the parameters are:

Parameter

Description

AddrT *macAddr

Address of the requesting ranging station (Peer A)

uint8_t *data

To deny the ranging request, a null value must be set; a pointer to


user data with a maximum of 100 bytes grants permission to ranging.

uint8_t *len

Length of the user data.

If Peer B has put user data in the Data packet when permission was granted, a data indication
is provided to Peer A.
void APLCallback (MsgT *msg)

where the message structure is:

Variable

Description

uint8_t prim;

PD_DATA_INDICATION

AddrT addr;

Source address of the Data packet.

uint8_t data[];

User data to be transmitted.

uint8_t len;

Length of user data with a maximum of 100 bytes.

The results of the ranging calculations performed previously is now provided to an application
on Peer B via a ranging indication. The is part of the time and energy saving feature of this
mode, It is now provided to the application.
Note: As the four accumulated time values T1, T2, T3, and T4 are stored in memory for use by
the next ranging request, the peer stations cannot communicate with other stations.

Page 18 NA-07-0240-0407-2.5

2010 Nanotron Technologies GmbH.

nanoLOC Ranging
nanoLOC nTRX Driver Suite User Guide

void APLCallback (MsgT *msg)

where the message structure is:


Variable

Description

uint8_t prim;

PD_RANGING_INDICATION

AddrT addr;

Address of the remote station (Peer B).

uint8_t data[];

Data includes RangingMsgT structure.

uint8_t len;

Length of user data with a maximum of 100 bytes.

The RangingMsgT structure is:


Variable

Description

uint8_t error;

Error status message.1

double distance;

Distance in meters between the peer stations.

AddrT addr;

Address of the remote station.

1.

3.3

See <Emphasis Footnote>Success and Error Messages on page 19

Success and Error Messages


After the ranging service is requested, a message will be received from the PHY layer with either a
success response or a failure response. In the case of success, the PHY layer will provide the
measured distance in meters. In the case of error, a status indication will provide the cause of the
error.
3.3.1 Success Messages
For normal ranging mode, the PHY layer sends to the application layer a message with the ranging
result having a message structure containing the following information:
Table 4: Message structure for callback

Variable

Description

MyByte8T prim;

PD_RANGING_INDICATION

MyAddrT addr;

MAC address of destination address which is the ranging target.

MyByte8T len;

Length of data in the data variable.

MyByte8T data[128];

Distance value (from RangingMSGT) and error status

MyByte8T status;

Not required for PD_RANGING_INDICATION

MyWord16T value;

Not required for PD_RANGING_INDICATION

MyByte8T attribute;

RANGING_TYPE_3W_A
RANGING_TYPE_3W_B
RANGING_TYPE_2W_PP

2010 Nanotron Technologies GmbH.

NA-07-0240-0407-2.5 Page 19

nanoLOC Ranging
nanoLOC nTRX Driver Suite User Guide

3.3.2 Error Messages


If an error condition occurs, the PHY layer will send to the application layer a message with the
message structure containing an error status.
Table 5: Message structure for callback

Variable

Description

MyByte8T prim;

PD_RANGING_INDICATION

MyAddrT addr;

MAC address of destination address which is the ranging target.

MyByte8T len;

Length of data in the data variable.

MyByte8T data[128];

Distance value (from RangingMSGT) and error status (see below)

MyByte8T status;

Not required for PD_RANGING_FAST_INDICATION

MyWord16T value;

Not required for PD_RANGING_FAST_INDICATION

MyByte8T attribute;

Not required for PD_RANGING_FAST_INDICATION

Error Status
+

RG_STAT_DEFAULT
Default value is 0x00 when ranging starts. No measurement have been done.

RG_STAT_NO_ERROR
When the value is 0x0F, then all parts of the measurements were performed successfully.

RG_STAT_VALUE_ERROR
Indicates ranging value not logical (value < 0)

RG_STAT_T1
If set, then measurement T1 measured correctly

RG_STAT_T2
If set, then measurement T2 measured correctly

RG_STAT_T3
If set, then measurement T3 measured correctly

RG_STAT_T4
If set, then measurement T4 measured correctly

RG_STAT_TIMEOUT
Measurement aborted due to non-answer from paired station. Only occurs when paired station
exists. The paired station has sent a hardware acknowledgement but did not provide a ranging
answer within the set time.

RG_STAT_VALUE_ERROR
Measurements from mirrored measurements are different and therefore rejected. For example,
The difference between the measurement results calculated using times T1 and T2 as well as
T3 and T4 should be no greater than 10 meters, based on the use of a 40 ppm quartz clock. If
the difference is greater than 10 meters, it will be reported in this error message.

Page 20 NA-07-0240-0407-2.5

2010 Nanotron Technologies GmbH.

Driver Demo Hardware Access/Interface Modules


nanoLOC nTRX Driver Suite User Guide

4 Driver Demo Hardware Access/Interface Modules


This section describes additional modules that are required for generating a full working demo
application. To generate this application, additional modules are required for accessing the hardware on the nanoLOC DK Board and for providing functions to use certain interfaces on the board.
These modules are described in the following sections.

4.1

appl.c Module User Application


4.1.1 Description
The appl.c module contains the user application. In this example it uses the serial interface to
build a wireless link between two terminals to transmit and receive ASCII (printable) characters.
4.1.2 Functions
void ApplCallback (uint8_t *addr, uint8_t *payload,
uint16_t length);
Purpose: This function receives every incoming message and sends the payload to the serial
interface.
void InitApplication (void);
Purpose:
buffers.

This function initializes variables used in the application, such as addresses and

void IsAlive (void);


Purpose:
LED.

This function indicates the operational state of the application through a blinking

void PollApplication (void);


Purpose: This function handles all user input and provides the configuration menu.

4.2

hwclock.c Module Timer


4.2.1 Description
The hwclock.c module handles the timer used for the indication LEDs on the nanoLOC DK
Board.

Functions
void hwclock_init (void);
Purpose: This function initializes the clock in the microcontroller.
uint32_t hwclock (void);
Purpose: This function returns the time in milliseconds since power-on.
SIGNAL (SIG_OVERFLOW0);
Purpose: Interrupt service routine that is called every 10 ms to update the time-tick counter. It
also monitors the keys on the nanoLOC DK Board.
Note: SIGNAL is a reserved word for interrupt service routines handling interrupts generated
by an ATMEL AVR microcontroller. For more information, refer to ATMEL AVR User
Guide.
2010 Nanotron Technologies GmbH.

NA-07-0240-0407-2.5 Page 21

4
4.3

Driver Demo Hardware Access/Interface Modules


nanoLOC nTRX Driver Suite User Guide

usart.c Serial Line


4.3.1 Description
The usart.c module handles the serial line on the nanoLOC DK Board.
4.3.2 Functions
void console_init (void);
Purpose: This function initializes the serial port of the microcontroller and redirects the stream
for input, output, and error messages.
SIGNAL(SIG_USART1_RECV);
Purpose: This function is the interrupt service routine to handle incoming data from the serial
interface.
int _getchar(FILE *stream);
Purpose: This function has to be provided for library I/O functions for default input.
int _putchar(char c, FILE *stream);
Purpose: This function has to be provided for library I/O functions for default output.
int kbhit (void);
Purpose: This function checks the input buffer of the serial interface for new data.
char *read_line (char buf[]);
Purpose: This function collects all incoming data from the serial line. Additionally, this function
handles backspaces and carriage return / linefeed conversion.

4.4

nnspi.c Module SPI Communication


4.4.1 Description
The nnspi.c module contains the hardware driver for the SPI communication between the AVR
microcontroller and the nanoLOC chip on the nanoLOC DK Board.
4.4.2 Function
void NanoReset (void);
Purpose: This function generates a defined reset impulse for the nanoLOC chip.
void InitSPI (void);
Purpose: This function initializes the SPI interface of the microcontroller.
void SetupSPI (void);
Purpose: This function configures the SPI interface to work in the same mode as the nanoLOC chip.
void NTRXReadSPI (uint8_t address, uint8_t *buffer,
uint8_t length);
Purpose: This function reads [length] bytes into [buffer] starting at [address].
void NTRXWriteSPI (uint8_t address, uint8_t *buffer, uint8_t length);
Purpose: This function writes [length] bytes from [buffer] into nanoLOC registers starting
at [address].
void nanosetIRQ (bool_t value);
Purpose: This function enables or disables the interrupt for the nanoLOC chip.

Page 22 NA-07-0240-0407-2.5

2010 Nanotron Technologies GmbH.

Driver Demo Hardware Access/Interface Modules


nanoLOC nTRX Driver Suite User Guide

4.5

main.c Module Main Loop


4.5.1 Description
The main.c module contains the startup code and the main control loop for the application.
4.5.2 Starting Up and Running an Application
To start up and run an application, the main function performs the following:
1

The hardware, timer, serial interface and I/O ports are initialized.
The procedure for initializing the hardware and I/O ports are dependent on the hardware and is,
therefore, not described here.

The SPI interface is initialized to communicate with the nanoLOC chip.


The procedure for initializing the SPI interface is depended on the user hardware and is, therefore, not described here

The nanoLOC chip is initialized.


See Initializing the nanoLOC TRX Transceiver on page 23

The user application is set up.


See Setting Up the User Application on page 23

The main loop is entered to check for user requests, receive data from the nanoLOC chip or
update the LEDs for indicating different events.
See The Main Loop on page 23.

4.5.3 Initializing the nanoLOC TRX Transceiver


To initialize the nanoLOC chip, do the following:
1

Call the following function to correctly initialize all registers for normal 80 MHz, 1 Mbit/s operation, and for starting the receiver:
void NTRXInit(void);

To allow an application to use the nanoLOC chip, the application must then set the MAC
address.
Note: In this example the nanoLOC chip is not interrupt driven.

4.5.4 Setting Up the User Application


To set up the user application, do the following:
1

Initialize the application using the following function:


void InitApplication (void);

Set the MAC address of nanoLOC chip for address matching and as sender address for transmitted messages.

Additional settings as required should be made at this point.

4.5.5 The Main Loop


The main loop periodically checks for events generated by the software (such as by application
requests) or by external events (such as by the nanoLOC chip). Timer events are interrupt driven
and handled by an interrupt service routine (ISR).
1

The following function is the user application and entry point for processing transmitted and
received data:
void PollApplication (void);

2010 Nanotron Technologies GmbH.

NA-07-0240-0407-2.5 Page 23

Driver Demo Hardware Access/Interface Modules


nanoLOC nTRX Driver Suite User Guide

The following function checks for incoming messages from the nanoLOC chip and delivers the
received data to the application:
void NTRXUpdate (void);

The following function is only used to provide visual feedback to the developer:
voidIsAlive (void);

4.5.6 Transmitting Messages


To transmit a message it is necessary to do the following steps:
1

Set the MAC header in the transmitter.

Write the payload to the transmit buffer in the nanoLOC chip.

Start the transmitter.

Send the message using the following function.


void NTRXSendMessage (uint8_t *addr, PtrT payload, uint16_t length)
where:
+

addr is the address of the recipient of the message

payload is a pointer to the data buffer containing the payload

length is the length of the payload in bytes

NTRXSendMessage calls the following three functions in succession:


+

NTRXTxHeader (addr, length, rsvd1, rsvd2, rsvd3);

NTRXTxData (payload, length);

NTRXTxStart ();

4.5.7 Receiving Messages


When a message has been successfully received, the NTRXUpdate function is used to read out
the header data and payload from the nanoLOC chip using the following functions:
void NTRXRxMacHeader (void);
and
void NTRXRxReceive (void);
After retrieving all necessary data, the receiver is restarted in order to be ready for the next message. The received data is then delivered to the upper layer. In this case the upper layer is the user
application itself.

Page 24 NA-07-0240-0407-2.5

2010 Nanotron Technologies GmbH.

Index
nanoLOC nTRX Driver Suite User Guide

Index
A

address matching ..................................................................... 1, 3


API
located in phy.c ......................................................................... 1
APPCallback............................................................................... 10
appl.c module ............................................................................. 21
ApplCallback............................................................................... 21
application layer............................................................................ 7
ARQ, enabling / disabling ............................................................. 2
ARQ, see Automatic Repeat Request
Automatic Repeat Request (ARQ)................................................ 3
automatic retransmissions ............................................................ 9

LayernameCallback ...................................................................... 4
LayernameMESAP ....................................................................... 4
LayernameSAP ............................................................................ 4
length of payload parameter ....................................................... 24
logical channel
attributes described................................................................... 9
Logical Network ID ................................................................... 2, 3

B
Brdcast packets ............................................................................ 3
Broadcast
key setting of nanoLOC TRX Driver.......................................... 2

C
callback function ........................................................................... 4
center frequency ........................................................................... 9
chip
initializing ................................................................................ 23
clock............................................................................................ 21
configuration menu ..................................................................... 21
CRC2 checking............................................................................. 2
CRC2 checking and nanoLOC TRX Driver................................... 3
CSMA/CA ................................................................................. 2, 3

D
data transmission rates............................................................. 1, 3
driver
accessing applications through ................................................. 1
and embedded applications ...................................................... 1
and PHY layer ........................................................................... 6
API ........................................................................................ 1, 3
demo described ...................................................................... 21
example implementation ........................................................... 2
general layer interface of .......................................................... 4
hardware ................................................................................. 22
key settings of ....................................................................... 2, 3
located in phy.c ......................................................................... 3
modules overview ..................................................................... 2
overview .................................................................................... 3
source code in phy.c module .................................................... 1
Driver Demo................................................................................ 21

E
embedded application, nanoLOC driver for .................................. 1
embedded applications
and nanoLOC driver.................................................................. 3
error checking ............................................................................... 1
error checking, function of nanoLOC TRX Driver ......................... 3
error messages, ranging............................................................. 20

F
FEC............................................................................................... 9
enabling by nanoLOC TRX Driver............................................. 3
Forward Error Correction, See FEC

G
generating full working demo...................................................... 21

H
Hardware Adaption Layer ............................................................. 5
hwclock ....................................................................................... 21
hwclock_init ................................................................................ 21
hwclock.c .................................................................................... 21

I
indication LEDs........................................................................... 21
InitApplication ....................................................................... 21, 23
initialization
microcontroller clock ............................................................... 21
of variables used in application ............................................... 21
initializing
chip ......................................................................................... 23
driver function for ...................................................................... 6
interrupt service routine ........................................................ 21, 23
IsAlive ......................................................................................... 21

2010 Nanotron Technologies GmbH.

M
MAC header ............................................................................... 24
main loop .................................................................................... 23
main.c ......................................................................................... 23
message
used in nanoLOC TRX Driver ................................................... 2
modulation methods ................................................................. 1, 3
module
appl.c ...................................................................................... 21
hwclock.c ................................................................................ 21
main.c ..................................................................................... 23
nnspi.c..................................................................................... 22
overview.................................................................................... 1
phy.c ......................................................................................... 1
relationships between ............................................................... 1
usart.c ..................................................................................... 22
MyMsgT ........................................................................................ 5

N
nanoLOC API ............................................................................... 3
nanoLOC chip
initializing ................................................................................ 23
nanoLOC nTRX Driver
and embedded applications ...................................................... 3
described .................................................................................. 3
NTRX_RTC ................................................................................ 10
NTRXInit ..................................................................................... 23
ntrxinit.c ........................................................................................ 1
NTRXInterrupt .............................................................................. 6
ntrxiqpar.c ..................................................................................... 1
NTRXRxMacHeader ................................................................... 24
NTRXRxReceive ........................................................................ 24
NTRXSendMessage................................................................... 24
NTRXTxData .............................................................................. 24
NTRXTxHeader .......................................................................... 24
NTRXTxStart .............................................................................. 24
ntrxtypes.h .................................................................................... 5
NTRXUpdate .............................................................................. 24
ntrxutil.c ........................................................................................ 1

O
output power
driver sets transmission output power ...................................... 2

P
parameter
length ...................................................................................... 24
payload ................................................................................... 24
payload ....................................................................................... 24
payload parameter...................................................................... 24
PD_DATA_CONFIRM .................................................................. 8
PD_DATA_INDICATION .............................................................. 8
PD_DATA_REQUEST.................................................................. 8
PHY Layer .................................................................................... 6
PHY_ADDR_MATCHING ........................................................... 10
PHY_ARQ .................................................................................... 9
PHY_CHANNEL ........................................................................... 9
PHY_FEC ..................................................................................... 9
PHY_LOG_CHANNEL ................................................................. 9
PHY_MAC_ADDRESS1............................................................. 10
PHY_PWR_DOWN_MODE........................................................ 10
PHY_RECALIBRATION ............................................................. 10
PHY_TX_POWER ........................................................................ 9
phy.c ............................................................................................. 1
PLME_GET_REQUEST ............................................................... 8
PLME_SET_REQUEST ............................................................... 8
PollApplication ...................................................................... 21, 23
Processing Delay........................................................................ 11

R
receiving messages .................................................................... 24
register
module for general access of.................................................... 1

NA-07-0240-0407-2.5 Page 25

Index
nanoLOC nTRX Driver Suite User Guide

return time................................................................................... 21

TimeB packets .......................................................................... 2, 3


timer, handled by hwclock.c ....................................................... 21
transceiver registers ................................................................. 2, 3
transmit buffer............................................................................. 24
transmit message ....................................................................... 24
TX Propagation Delay ................................................................ 11

SAPs............................................................................................. 4
SDS-TWR ................................................................................... 11
serial interface ............................................................................ 21
Service Access Points, see SAPs
SIGNAL....................................................................................... 21
SIGNAL (SIG_OVERFLOW0) .................................................... 21
SPI interface ............................................................................... 23
starting up and running application............................................. 23
success messages, ranging ....................................................... 19

Page 26 NA-07-0240-0407-2.5

U
user application .......................................................................... 21
user input .................................................................................... 21

V
voidIsAlive .................................................................................. 24

2010 Nanotron Technologies GmbH.

Revision History
nanoLOC nTRX Driver Suite User Guide

Revision History
Version

Date

Description/Changes

1.00

2007-03-15

Initial version.

1.1

2007-11-09

minor textual edits; NTRXSetTxDestAddress function no longer included; new parameter added to NTRXSendMessage; NTRXPowerdownMode function added; addr parameter added to ApplCallback function; iohigh and iolow modules replaced by usart.c
module which handles the serial line on the nanoLOC DK Board; in section 3.5.6 destination address now set by a parameter in NTRXSendMessage function; description of
ranging functions added.

2.0

2007-12-12

nanoLOC API section updated; nanoLOC Ranging section updated; minor text edits
throughout.

2.1

2008-04-07

Updated template, minor text changes.

2.2

2008-08-08

Index added; chip configuration details and code example added; general edit throughout.

2.3

2009-04-28

The following data type names where modified:


MyByte8T -> uint8_t
MyAddrT -> AddrT
MyWord16T -> uint16_t
MyBoolT -> bool_t
MyMsgT -> MsgT
MyDword32T ->uint32_t

2.5

2010-03-31

Updated API, Ranging, and introduction.

2010 Nanotron Technologies GmbH.

Page 27 NA-07-0240-0407-2.5

Revision History
nanoLOC nTRX Driver Suite User Guide

About Nanotron Technologies GmbH

Further Information:

Nanotron provides reliable loss protection technology and solutions that are
used to protect people and animals. Energy efficient, battery- powered wireless nodes are the key building blocks. These small devices create a Virtual
Safety Zone which protects tagged people and animals. Robust wireless
Chirp technology underpins nanotron's offering of chips, modules and loss
protection software for indoor and outdoor environments world wide.

For more information about this product and other products from Nanotron
Technologies, contact a sales representative at the following address:
Nanotron Technologies GmbH
Alt-Moabit 60, 10555 Berlin, Germany
Phone: +49 30 399 954 - 0 | Fax: +49 30 399 954 - 188
Email: sales@nanotron.com | Internet: www.nanotron.com

Das könnte Ihnen auch gefallen