Skip to main content

Nordic nRF52 Developer Setup

This walkthrough will help you set up the Swaralink BLE Platform middleware for development with our API. From cloning the Swaralink BLE git repo to installing the Integrated Development Environment (IDE) to begin developing with the Nordic Semiconductors nRF52 device family.

Please be aware that the following guide assumes you are using Windows. The exact steps or instructions may be slightly different for Mac OS and Linux.

Note: To complete the full build process, you will need to obtain the swl_periph middleware library from Swaralink Technologies. The library will be provided upon execution of a license agreement with Swaralink Technologies. For more information on obtaining a license, please contact swaralink Technologies at info@swaralink.com.
In the meantime, feel free to go through the remainder of the setup and application guide to understand the process of building a project and to get a walkthrough of the code. You can also browse around the SwaraLink Demo project source code and take a look at our API in the header files.

1. Clone the Git Repo

First, to get access to the Swaralink BLE Platform you must begin by cloning our git repository, which is located here:

SwaraLink swl_periph repo on Github

Using Git Bash, or any other Git client, clone the repo using the following command:

    git clone git@github.com:SwaraLinkTechnologies/swl_periph.git

You can clone the repo anywhere on your local hard drive; the only restriction is that you do not have any spaces in any of the directory names. So for example, cloning to "C:\swl_periph, "C:\git\swl_periph", or "C:\development\ble\swl_periph" would all be acceptable options.

For the remainder of this documentation, we will assume that you cloned the repo to the directory "C:\git\swl_periph". If you chose a different location, be sure to adjust the instructions accordingly.

If you don't wish to use Git, you can alternatively download the contents in a zip file. Go to our github repo page, click the "Code" button on the upper right, and select "Download ZIP" to. Once the zip file is downloaded the contents can be extracted the directory of your choice.

2. Download the Nordic nRF5 SDK

Next, download the nRF5 SDK (v17.0.2). The only required ZIP file is nRF5_SDK_17.0.2_d674dde.zip shown below.
resize

Once downloaded, please guarantee the downloaded SDK is in the same directory with the downloaded swl_periph git code like so:

    root
|___ nRF5_SDK_17.0.2_d674dde
| |___components
| |___config
| |___documentation
| |___examples
| |___external
| |___external_tools
| |___integration
| |___modules
|
|___ swl_periph
|___platform
|___swl_periph

root = "C:\git\"

3. Install the SEGGER Embedded Studio for ARM IDE

To develop and build an application you should install the following Integrated Development Environment (IDE): SEGGER Embedded Studio for ARM 5.42b

In order for the platform code to build successfully, you will need the SWL peripheral library which is provided by SwaraLink under license. The swl_periph library holds the internal workings required for our API to work.

The .a file must be placed in the directory C:\git\swl_periph\swl_periph\lib\swl_periph_nrf_52\ as instructed by the README file inside.

Building a project on SEGGER Embedded Studio without this library will result in the following error:


Project and Application Walkthrough

Once all the files are in place, open up SEGGER Embedded Studio (SES), and under the "File" menu select "Open Solution". Navigate to the following directory:

C:\git\swl\swl_periph\platform\nrf52832_nrf5_sdk_17.0.2\swl\nordic_example_swl_periph\pca10040\s132\ses

From there, open up the file: swl_periph_nrf_pca10040_s132.emProject.

Upon opening the .emProject file, SES will launch and all project files can be viewed under the Project Explorer. The project files can be separated into three basic categories: Application, SWL Peripheral, and nRF52 SDK. For this walkthrough, the focus will be on the Application and SWL Peripheral files.

Under the Project Explorer in SES, navigate to the swl_periph group of files and open the swl_periph.h file as well as main.c within the Application group.

Inside swl_periph.h you can become acquainted with the SwaraLink Embedded Peripheral (swl_periph) API. The key defined variable data types and function prototypes can be found here, along with detailed descriptions in the comments.

The peripheral events found in the enumeration swl_periph_evt_t define all of the possible events that can be generated by the middleware and that are processed in the application's event handler function (periph_evt_handler, found in main.c).

So for example: when a Bluetooth connection has been established between the peripheral and a central device (that is running the SwaraLink Mobile Central Middleware library, aka "SWLCentral"), the swl_periph library will generate a SWL_PERIPH_EVT_CONN_ESTABLISHED event identified by the value 0x00.

In addition to the event type, the peripheral event handler also includes a second parameter: a pointer to an swl_periph_evt_data_t object containing data associated with the event. As a union, the specific type of the data is dependent on the type of the event. So in the case of the library generating an SWL_PERIPH_EVT_CONN_ESTABLISHED event, the data object will contain a swl_conn_establish_t structure within it. The event handler will proceed to turn on LED 1 on the development kit (DK) to signal the newly connected state as well as set the boolean ble_connection_established variable to true.

Here are a few other examples of events that are generated by the peripheral library:

  • SWL_PERIPH_EVT_RX_DATA

    • This event occurs whenever the peripheral device receives data from its central peer. In this case, the peripheral event handler will call the function handle_rx_data() with the swl_periph_evt_data_t union member, swl_c2p_data_t (SWL Central-To-Peripheral Data).

      The swl_c2p_data_t struct holds the pertinent information for the incoming data, such as: major and minor headers, device ID, a pointer to the received data, etc. These data fields are used within the handle_rx_data() function to process the data if the major is set to the required major as specified by ID_HDR_MAJ_P2C_DEMO_REQ and one of few defined minor headers located within swl_periph_demo.h.

      Drawing back to the nRF52 demo, the major header that was utilized to usefully demonstrate SWLCentral.sendData in step 7 was 00, which is what ID_HDR_MAJ_P2C_DEMO_REQ is defined as.
  • SWL_PERIPH_PRIO_UPDATE

    • This event takes place when the peripheral device has successfully updated its priorities, as defined in the Terminology page. During this case, the event data object will contain the struct swl_periph_prio_updated_t which is composed of three variables of type swl_priority_t to identify the three updated priorities. The mentioned swl_priority_t is a simple enumeration containing the three possibile priorities to be chosen from, all found within our API in swl_periph.h.
      The peripheral event handler goes on to log the updated priorities, accessed through the swl_periph_prio_updated_t type event data object.
  • SWL_PERIPH_EVT_CONN_TERMINATED

    • This event is generated when the peripheral device successfully terminates the connection with its central peer. In this case, the union type swl_periph_evt_data_t event data object will contain the struct swl_conn_terminate_t which contains the device ID of the disconnected central. The event handler proceeds to clear LED 1 and the connection established flag, which were both set during the SWL_PERIPH_EVT_CONN_ESTABLISHED event discussed above.

Up to this point, we have discussed notable data types and how they are utilized by the peripheral event handler to process the data as defined by the corresponding event. The logic to process these different events is greatly comprised of SWL API functions whose prototypes can also be found in swl_periph.h. The following are a few function examples:

  • swl_periph_p2c_tx_by_copy()

    • Use this function to queue a peripheral-to-central transmission executed by directly copying the data into the transmission buffer.
    • Does not require that the data being sent is preserved by the application, as it is replicated into the buffer.
    • Accepts a pointer to the data, the length of the data, boolean variable to request an acknowledgement from the central, a major ID, and a minor ID.
    • Returns swl_err_t as: SWL_SUCCESS, SWL_ERR_INVALID_PARAM, SWL_ERR_INVALID_SIZE, SWL_ERR_INSUFFICIENT_MEMORY, SWL_ERR_INSUFFICIENT_BUFFERS, or SWL_ERR_CRITICAL.
  • swl_periph_p2c_tx_by_ref()

    • Use this function to queue a peripheral-to-central transmission executed by using a reference to the data in your application for the transmission buffer.
    • Requires that the data being sent is preserved by the application until the SWL_PERIPH_EVT_DATA_SENT event is generated, as any change in the data will be referenced to while queued or during operation.
    • Accepts a pointer to the data, the length of the data, boolean variable to request an acknowledgement from the central, a major ID, and a minor ID.
    • Returns swl_err_t as: SWL_SUCCESS, SWL_ERR_INVALID_PARAM, SWL_ERR_INVALID_SIZE, SWL_ERR_INSUFFICIENT_MEMORY, SWL_ERR_INSUFFICIENT_BUFFERS, or SWL_ERR_CRITICAL.
  • swl_periph_set_peripheral_priorities()

    • This function can be called to set what will be prioritized by the peripheral device; between power consumption, data throughput, and communication range.
    • Accepts three swl_priority_t type variables that indicate highest, second highest, and third highest priorities.
    • Returns swl_err_t as: SWL_SUCCESS or SWL_ERR_OPERATION_IN_PROG.

The swl_err_t and the error codes belonging to it are defined in the swl_types.h file.

Another key feature of the SWL API is the exception handler function (exception_handler, found in main.c). This handler gets called whenever an error is caught in the peripheral library with a pointer to a struct of type swl_periph_exception_data_t, containing information to do with the origin of the exception in the code as well as metadata generated by the exception. Like all other API data types, this struct is defined in swl_periph.h.

The exception handler proceeds to log the precise location in the code where the exception occured as well as its metadata. After logging the contents of the exception data struct, the log is then dumped to save and identify the state of the code when the exception occured. This dumped diagnostic log should be reported to SwaraLink for further analysis on the peripheral platform. Lastly, the exception handler triggers a breakpoint if the debugger is connected, otherwise it proceeds to reset the CPU.

One more header file worth reading is swl_periph_app_config.h in the Application directory. Here, we define peripheral application parameters such as the transmission buffer size and the intial peripheral priorities.

Note that the initial priorities are all set to increase throughput, which was observed in the demo documentation when first connecting the SWLCentral mobile device and the peripheral DK. Initially, we recommend you do not modify these values until further familiariziation with the platform.