TABLE OF CONTENTS

• Introduction
  • What you'll learn
  • What you’ll need
• Getting Started
• Docker Installation
• git Installation
• Wirepas SDK installation
  • Clone the Repository
• Wirepas Massive Stack Download
• Build an application
  • Clean the build
  • Create you own application
• Microsoft Visual Studio Code Example
• Frequently Asked Questions
• References
• Revision History
• Legal Notice

Introduction

In this How To you’ll install Wirepas SDK and build an application using the Docker based build environment. 

What you'll learn

• Installing the Wirepas Massive SDK from Github
• Selecting the right version using Git
• Installing Docker and building an application using the Docker Build environment

What you’ll need

• A PC compliant with Docker installation as per requirements available here.
• Access to Wirepas Massive stack. To request access just create a ticket in the Developer Portal following this link and select “Stack Sharefile account request” in Request Type.
• Microsoft Visual Studio Code available here.

This document describes Windows based installation, requirement shall be adjusted to your OS if you use Linux or MacOS

Getting Started

Wirepas Massive SDK is based on GNU ARM toolchain and has a few dependencies to be solved.

The Docker build environment allows to have a containerized build environment where all dependencies are solved. It simplifies a lot the environment setup as only Docker dependency needs to be solved. In addition it makes the build environment agnostic of the host OS.

In this How to we describe the installation on a Windows machine together with Microsoft Visual Studio Code IDE as an example. The same approach can be easily deployed on Linux or MacOS, please refer to Docker website for more details.

Note: Docker is not a mandatory requirement to use Wirepas Massive SDK. Native installation can be also performed. The Docker environment offers a lot of advantages such as OS independence, and dependencies already solved.

In the next chapters you will setup and build an application in 5 steps

• Docker & Git installation
• Wirepas SDK installation
• Wirepas Massive Stack installation
• Build a Wirepas application
• Working with Wirepas SDK using Visual Studio Code

The docker build environment is supported from Wirepas Massive SDK v1.0.2 onward. 

Docker Installation

Docker based build environment offers quick and easy way of building the application with Wirepas SDK. Docker can be installed on different operating system. 

Please follow the Docker installation for your OS from: https://docs.docker.com/get-docker/.

Make sure you comply with requirements described in the installation procedure. As an example for Windows: https://docs.docker.com/docker-for-windows/install/#what-to-know-before-you-install

git Installation

Download and install the git client from link: https://git-scm.com/downloads. Follow the default installation options.

With the docker build approach, source code will be accessed by Windows native OS but also by Linux from the Docker container. To avoid issues with line endings, it is important to avoid Git changing LF to CRLF for Windows. Otherwise, Docker image will have issues when accessing the code. To avoid such conflicts, core.autocrlf shal be set to input .
Launch git-bash from start menu and run the following command to set the core.autocrlf = Input:

git config --global core.autocrlf input

In case of any errors while setting core.autocrlf you can:

• Try again but by running git-bash as administrator
• if still not successful manually edit gitconfig file to set: autocrlf = input

Wirepas SDK installation

The latest release of Wirepas SDK is available from github.com/wirepas/wm-sdk

Clone the Repository

Launch git-CMD from start menu to clone or pull the latest version of the Wirepas SDK repository using command from the directory where you want to install the SDK:

git clone https://github.com/wirepas/wm-sdk.git

Change to the directory of the repo you just cloned

cd wm-sdk

Checkout the wanted tagged release in case you don't want to stay on the master branch (currently you are on the master branch). Make sure you checkout the version corresponding to the Wirepas Massive stack release you are using as indicated in the respective Release Note [3] by looking at the SDK release history: https://github.com/wirepas/wm-sdk/releases 

git checkout <Tag Version ie: v1.2.0 corresponding to Wirepas Massive v5.1>

Optionally, create your own branch so you can customize Wirepas Massive and use version control on it

git branch my-new-branch-name

Wirepas Massive Stack Download

You need to have a valid Wirepas Massive license to download the Wirepas Massive Stack. 

The stack is available from Wirepas Sharefile. 

• Go to Wirepas developer portal https://developer.wirepas.com/ and click on the Sharefile link at the top.
• Then navigate to Wirepas Massive 2.4GHz > V5.x Releases
• Navigate to the folder corresponding to your release version.
• Download the compressed file for your target MCU, you can place multiple images in the folder if you are doing projects using more than one MCU type.
• Extract your binary stack image.
• Copy the Wirepas Massive stack binaries into the image folder of the SDK.

SDK User Manual is available at  https://wirepas.github.io/wm-sdk/index.html 

Build an application

Once Docker and SDK folders are ready, follow the below steps to build an application. We describe here how to build the custom_app for a pca10040 board.

• Open terminal (cmd or powershell)
• Use below command to build the application in the terminal (parameter in bold should be configured on your machine). Please note that relative path are not supported.

docker run --rm -v /c/wirepas/wm-sdk:/home/wirepas/wm-sdk -w /home/wirepas/wm-sdk -ti wirepas/sdk-builder:v1.2 make app_name=custom_app target_board=pca10040

NOTE: the “--rm“ command line option is used to automatically clean-up the container’s file system after each build. 

• The above command uses the application code in the SDK on the local machine to generate the application binary using the docker's build environment. Here are the details of the command format:
  • "/c/wirepas/wm-sdk " shall be adapted to point to the location of the Wirepas SDK folder on your local machine.
  • "app_name=custom_app" is the pointing to the application code. In the example, custom_app is being compiled."target_board=pca10040" is the selecting the relevant board to compile & build the application code. In example, Pca10040 refers to the nRF52832 board. Modify the config.mk in the application source folder to define the types of boards the application can be built for. The list of the boards and their associated target_name is presented at the end of this chapter. 
  • “wirepas/sdk-builder:v1.2”: This tag is used to select the proper Docker image and depends on the SDK version in used. Tag is v1.2 for existing versions.
  • "/home/wirepas/wm-sdk" is the mounting point of the location folder in Docker and should not be changed
  • "make" is the command to compile the application in Docker and should not be changed
  • More details on the build command can be found in SDK documentation here.
• At first execution:
  • docker will automatically download the proper container from dockerhub.
  • You will be prompted to review the license
  • You will be prompted to input or generate Bootloader keys.

As example, you can verify that everything works as expected by building a Custom app for pca10040 board based on nRF52832 and checking that .hex files are present in build folder (make sure you have installed the nRF52832 stack binary, otherwise adjust the command to your board):

Note: This How To only focuses on having a functional build environment. You will find in References section links to the next documents.

You will find below a reference table for the target board names :

Clean the build

Use the following command to clean the build:

docker run --rm -v /c/user/admin/wirepas/wm-sdk:/home/wirepas/wm-sdk -w /home/wirepas/wm-sdk -ti wirepas/sdk-builder:v1.2 make app_name=custom_app target_board=pca10040 clean

Other parameters are the same as for the build command.

The command is executed as previously done, but with additional tag "clean", to clean the earlier build.

NOTE: You need to clean the build if you modify config.mk file, in example to change network parameters.

Create you own application

You can now start to develop your custom application code and follow the above steps to compile and build the application. You can find more details on how to create you own custom application from the following chapter in SDK documentation.

Microsoft Visual Studio Code Example

Wirepas SDK can be used with various IDEs for application development. However the Microsoft Visual Studio Code (VS-Code) is commonly used by Wirepas partners globally.

Here is an example to configure and execute the build task using the VS-code:

• Open Wirepas SDK In VS Code IDE : File -> Open Folder --> Browse to C:\user\admin\wirepas\wm-sdk
• Select (from top bar): Terminal --> New Terminal
• You can then run the same command(s) as in "Build an Application" above to build your project.
  

Frequently Asked Questions

Q: I would like to use another IDE, how do I do that?

A: The Wirepas SDK relies on Makefiles and uses GCC make. It is completely independent from the IDE. It can be used with IDEs based on developers comfort level. The requirements and dependencies for SDK installation are described in Wirepas Github SDK page. You will need to tell your IDE to use GCC make to compile your project.

Q: Do I need to use Docker? 

A: Wirepas provides the build environment as a Docker container for convenience. The Docker environment offers a lot of advantages such as OS independence, and dependencies already solved (available here). You can directly compile your project using Make as long as you have solved the dependencies.

Q: Do I need to use git?

A: No, you can use the zip or tar.gz file from github releases to download wm-sdk, however using git will make it significantly easier to update your code to the latest Wirepas releases in the future.
The latest release of Wirepas SDK is available from github. Here the links to access:
github link: https://github.com/wirepas/wm-sdk
You can download the SDK via Git command or via direct download as a zip.
Here is an example to download as a ZIP:

• Go to: https://github.com/wirepas/wm-sdk 
• Select the right version by selecting the right Tag (here 1.02)
• Then click on "Code" and "Download ZIP"

References

[1] Wirepas SDK Documentation: https://wirepas.github.io/wm-sdk/
[2] How To Flash Wirepas Application
[3] Wirepas Massive Stack Release notes

Revision History

Legal Notice

Use of this document is strictly subject to Wirepas’ Terms of Use and Legal Notice.

Copyright © 2021 Wirepas Oy