RIOT/pkg/semtech-loramac/doc.txt

/**
 * @defgroup pkg_semtech-loramac   Semtech LoRaMAC implementation
 * @ingroup  pkg
 * @ingroup  net
 * @brief    Provides a RIOT adaption of Semtech LoRaMAC implementation
 *
 * # Introduction
 *
 * This package provides an API built on top of the
 * [Semtech LoRaMAC-node](https://github.com/Lora-net/LoRaMac-node) reference
 * implementation of a LoRa network.
 *
 *
 * # Importing this package in an application
 *
 * This package only works with Semtech SX1272 and SX1276 radio devices. Thus,
 * in order to use it properly, the application `Makefile` must import the
 * corresponding device driver:
 * ```
 *     USEMODULE += sx1272  # for a SX1272 radio device
 *     USEMODULE += sx1276  # for a SX1276 radio device
 * ```
 *
 * In order to use this package in an application, add the following in
 * the application `Makefile`:
 * ```
 *     USEPKG += semtech-loramac
 * ```
 *
 * Since the LoRa radio depends on regional parameters regarding the access
 * to the physical support, the region where the device is used needs to be
 * set at compile time. Example for EU868:
 * ```
 *     CFLAGS += -DREGION_EU868
 *     CFLAGS += -DLORAMAC_ACTIVE_REGION=LORAMAC_REGION_EU868
 * ```
 *
 * # Using the package API
 *
 * The package provides a simple API for initializing the MAC, setting/getting
 * parameters, joining a network and sending/receiving packets to/from a LoRa
 * Network.
 *
 * In your `main.c`, some header files must be first included:
 * ```c
 *     #include "net/loramac.h"     /* core loramac definitions */
 *     #include "semtech_loramac.h" /* package API */
 * ```
 *
 * Then define global variables:
 * ```c
 *     semtech_loramac_t loramac;  /* The loramac stack device descriptor */
 *     /* define the required keys for OTAA, e.g over-the-air activation (the
 *        null arrays need to be updated with valid LoRa values) */
 *     static const uint8_t deveui[LORAMAC_DEVEUI_LEN] = { 0x00, 0x00, 0x00, 0x00, \
 *                                                         0x00, 0x00, 0x00, 0x00 };
 *     static const uint8_t appeui[LORAMAC_APPEUI_LEN] = { 0x00, 0x00, 0x00, 0x00, \
 *                                                         0x00, 0x00, 0x00, 0x00 };
 *     static const uint8_t appkey[LORAMAC_APPKEY_LEN] = { 0x00, 0x00, 0x00, 0x00, \
 *                                                         0x00, 0x00, 0x00, 0x00, \
 *                                                         0x00, 0x00, 0x00, 0x00, \
 *                                                         0x00, 0x00, 0x00, 0x00 };
 * ```
 *
 * Now in the `main` function:
 * 1. initialize the LoRaMAC MAC layer
 * 2. set the LoRa keys
 * 3. join the network
 * 4. send some data to the network
 * 5. wait for any potentially received data
 *
 * ```c
 * int main(void)
 * {
 *     /* 1. initialize the LoRaMAC MAC layer */
 *     semtech_loramac_init(&loramac);
 *
 *     /* 2. set the keys identifying the device */
 *     semtech_loramac_set_deveui(&loramac, deveui);
 *     semtech_loramac_set_appeui(&loramac, appeui);
 *     semtech_loramac_set_appkey(&loramac, appkey);
 *
 *     /* 3. join the network */
 *     if (semtech_loramac_join(&loramac, LORAMAC_JOIN_OTAA) != SEMTECH_LORAMAC_JOIN_SUCCEEDED) {
 *         puts("Join procedure failed");
 *         return 1;
 *     }
 *     puts("Join procedure succeeded");
 *
 *     /* 4. send some data */
 *     char *message = "This is RIOT";
 *     if (semtech_loramac_send(&loramac,
 *                              (uint8_t *)message, strlen(message)) != SEMTECH_LORAMAC_TX_OK) {
           printf("Cannot send message '%s'\n", message);
 *         return 1;
 *     }
 *
 *     /* 5. wait for any potentially received data */
 *     if (semtech_loramac_recv(&loramac) == SEMTECH_LORAMAC_DATA_RECEIVED) {
 *         loramac.rx_data.payload[loramac.rx_data.payload_len] = 0;
 *         printf("Data received: %s, port: %d\n",
 *                (char *)loramac.rx_data.payload, loramac.rx_data.port);
 *     }
 * }
 * ```
 *
 * @warning It is not possible to directly call the original LoRaMAC-node API
 *          using this package. This package should only be considered as a
 *          wrapper around the original LoRaMAC-node API and only the API
 *          provided by this package should be used.
 *
 * # License
 *
 * The library is using the BSD 3-clause license.
 *
 * @see      https://github.com/Lora-net/LoRaMac-node
 */