From ddac0aa483dd5f7bca31b0c042949eca370a8fdc Mon Sep 17 00:00:00 2001 From: Sylvain Miermont Date: Thu, 8 Aug 2013 15:49:31 +0200 Subject: Beta 3 - modified 'native' SPI module to align with the way resource pointers are managed in 'ftdi' variant (void pointers) - better check of channel frequency + bandwidth vs. authorized band - improved Makefile --- loragw_hal/README | 195 ------------------------------------------------------ 1 file changed, 195 deletions(-) delete mode 100644 loragw_hal/README (limited to 'loragw_hal/README') diff --git a/loragw_hal/README b/loragw_hal/README deleted file mode 100644 index 1e97a25..0000000 --- a/loragw_hal/README +++ /dev/null @@ -1,195 +0,0 @@ -Lora Gateway HAL -================ - -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, FSK or GFSK -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) - -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 flag is defined (eg. for GCC, add the -DDEBUG flag). - - -4. Hardware dependencies ------------------------- - -The loragw_reg and loragw_hal are written for a specific version on the Semtech -hardware. -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. - -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 (not provided) -* native SPI using a microcontroller peripheral (not provided) - -You can use the test program test_loragw_spi to check with a logic analyser -that the SPI communication is working - - -5. Usage --------- - -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: - - - -loop { - - - -} - - -To debug your application, it might help to compile the loragw_hal function -with the DEBUG flag defined. -It then send a lot of details, including detailed error messages to *stderr*. - - -**/!\ 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. - -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). - - -6. License ----------- - -To Be Defined. - - -*EOF* \ No newline at end of file -- cgit v1.2.3