summaryrefslogtreecommitdiff
path: root/libloragw/doc/MANUAL.TXT
blob: a08676187a7484e5f65278eab97098f1054783cb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
	 / _____)             _              | |    
	( (____  _____ ____ _| |_ _____  ____| |__  
	 \____ \| ___ |    (_   _) ___ |/ ___)  _ \ 
	 _____) ) ____| | | || |_| ____( (___| | | |
	(______/|_____)_|_|_| \__)_____)\____)_| |_|
		©2013 Semtech-Cycleo

Lora Gateway HAL user manual
============================

1. Introduction
---------------

The Lora Gateway Hardware Abstraction Layer is a C library that allow you to
use a Semtech Lora gateway hardware through a reduced number of high level C
functions to configure the hardware, send and receive packets.

The Semtech Lora gateway is a digital multi-channel multi-standard packet radio
used to send and receive packets wirelessly using Lora or FSK modulations.


2. Components of the library
----------------------------

The library is composed of 4 modules:

* loragw_hal
* loragw_reg
* loragw_spi
* loragw_aux

The library also contains 3 test program to demonstrate code use and check
functionality.

### 2.1. loragw_hal ###

This is the main module and contains the high level functions to configure and
use the Lora gateway:

* lgw_rxrf_setconf, to set the configuration of the radio channels
* lgw_rxif_setconf, to set the configuration of the IF+modem channels
* lgw_start, to apply the set configuration to the hardware and start it
* lgw_stop, to stop the hardware
* lgw_receive, to fetch packets if any was received
* lgw_send, to send a single packet (non-blocking, see warning in usage section)
* lgw_status, to check when a packet has effectively been sent

For an standard application, include only this module.
The use of this module is detailed on the usage section.

### 2.2. loragw_reg ###

This module is used to access to the Lora gateway registers by name instead of
by address:

* lgw_connect, to initialise and check the connection with the hardware
* lgw_disconnect, to disconnect the hardware
* lgw_soft_reset, to reset the whole hardware by resetting the register array
* lgw_reg_check, to check all registers vs. their default value and output the
result to a file
* lgw_reg_r, read a named register
* lgw_reg_w, write a named register
* lgw_reg_rb, read a name register in burst
* lgw_reg_wb, write a named register in burst

This module handles pagination, read-only registers protection, multi-byte
registers management, signed registers management, read-modify-write routines
for sub-byte registers and read/write burst fragmentation to respect SPI
maximum burst length constraints.

It make the code much easier to read and to debug.
Moreover, if registers are relocated between different hardware revisions but
keep the same function, the code written using register names can be reused "as
is".

If you need access to all the registers, include this module in your
application.

**/!\ Warning** please be sure to have a good understanding of the Lora gateway
inner working before accessing the internal registers directly.

### 2.3. loragw_spi ###

This module contains the functions to access the Lora gateway register array
through the SPI interface:

* lgw_spi_r to read one byte
* lgw_spi_w to write one byte
* lgw_spi_rb to read two bytes or more
* lgw_spi_wb to write two bytes or more

Please *do not* include that module directly into your application.

**/!\ Warning** Accessing the Lora gateway register array without the checks
and safety provided by the functions in loragw_reg is not recommended.

### 2.4. loragw_aux ###

This module contains a single host-dependant function wait_ms to pause for a
defined amount of milliseconds.

The procedure to start and configure the Lora gateway hardware contained in the
loragw_hal module requires to wait for several milliseconds at certain steps,
typically to allow for supply voltages or clocks to stabilize after been
switched on.

An accuracy of 1 ms or less is ideal.
If your system doesn't allow that level of accuracy, make sure that the actual
delay is *longer* that the time specified when the function is called (ie.
wait_ms(X) *MUST NOT* before X milliseconds under any circumstance).

If the minimum delays are not guaranteed during the configuration and start
procedure, the hardware might not work at nominal performance.
Most likely, it will not work at all.


3. Software dependencies
------------------------

The library is written following ANSI C conventions but using C99 explicit
length data type for all data exchanges with hardware and for parameters.

The loragw_aux module contains POSIX dependant functions for millisecond
accuracy pause.
For embedded platforms, the function could be rewritten using hardware times.

All modules use the fprintf(stderr,...) function to display debug diagnostic
messages if the DEBUG_xxx is set to 1 in library.cfg

Depending on config, SPI module needs LibMPSSE to access the FTDI SPI-over-USB
bridge. Please go to that URL to download that library:
http://code.google.com/p/libmpsse/

The code was tested with version 1.3 of LibMPSSE:
http://libmpsse.googlecode.com/files/libmpsse-1.3.tar.gz
SHA1 Checksum: 	1b994a23b118f83144261e3e786c43df74a81cd5

That library has some dependencies itself, please read the installation
instructions.


4. Hardware dependencies
------------------------

### 4.1. Hardware revision ###

The loragw_reg and loragw_hal are written for a specific version on the Semtech
hardware (IP and/or silicon revision).
All relevant details are contained in the VERSION.TXT file.

The library will not work if there is a mismatch between the hardware version 
and the library version. You can use the test program test_loragw_reg to check 
if the hardware registers match their software declaration.

### 4.2. SPI communication ###

loragw_spi contains 4 SPI functions (read, write, burst read, burst write) that
are platform-dependant.
The functions must be rewritten depending on the SPI bridge you use:

* SPI master matched to the Linux SPI device driver (provided)
* SPI over USB using FTDI components (provided)
* native SPI using a microcontroller peripheral (not provided)

Edit library.cfg to chose which SPI physical interface you want to use.

You can use the test program test_loragw_spi to check with a logic analyser
that the SPI communication is working


5. Usage
--------

### 5.1. Setting the software environment ###

For a typical application you need to:

* include loragw_hal.h in your program source
* link to the libloragw.a static library during compilation
* link to the librt library due to loragw_aux dependencies (timing functions)
* link to the libmpsse library if you use a FTDI SPI-over-USB bridge

For an application that will also access the concentrator configuration 
registers directly (eg. for advanced configuration) you also need to:

* include loragw_reg.h in your program source

### 5.2. Using the software API ###

To use the HAL in your application, you must follow some basic rules:

* configure the radios path and IF+modem path before starting the radio
* the configuration is only transferred to hardware when you call the *start*
function
* you cannot receive packets until one (or +) radio is enabled AND one (or +)
IF+modem part is enabled AND the gateway is started
* you cannot send packets until one (or +) radio is enabled AND the gateway is
started
* you must stop the gateway before changing the configuration

A typical application flow for using the HAL is the following:

	<configure the radios and IF+modems>
	<start the Lora gateway>
	loop {
		<fetch packets that were received by the gateway>
		<process, store and/or forward received packets>
		<send packets through the gateway>
	}
	<stop the gateway>

**/!\ Warning** The lgw_send function is non-blocking and returns while the
Lora gateway is still sending the packet, or even before the packet has started
to be transmitted if the packet is triggered on a future event.
While a packet is emitted, no packet can be received (limitation intrinsic to
most radio frequency systems).

Your application *must* take into account the time it takes to send a packet or 
check the status (using lgw_status) before attempting to send another packet.

Trying to send a packet while the previous packet has not finished being send
will result in the previous packet not being sent or being sent only partially
(resulting in a CRC error in the receiver).

### 5.3. Debugging mode ###

To debug your application, it might help to compile the loragw_hal function
with the debug messages activated (set DEBUG_HAL=1 in library.cfg).
It then send a lot of details, including detailed error messages to *stderr*.


*EOF*