Getting started with Sensor SW 2.0

These instructions help you to get started with Movesense sensor software development (v. 2.0 and later). Do read this carefully since the toolchains have been completely changed from earlier versions!

This section is split into four parts:

What's new in 2.0

Toolchain and usage

Software requirements

The following tools need to be installed in order to run the examples in this document.

Mandatory

Optional

Movesense device library is available here.

Build commands (Real HW)

First pull the Movesense build environment container:

docker pull movesense/sensor-build-env:latest

To successfully build the Movesense software it's required to clone the Movesense-device-lib repository:

git clone git@bitbucket.org:movesense/movesense-device-lib.git

After that go to the cloned repository folder

cd movesense-device-lib

start the docker image on terminal:

Linux or Mac:

docker run -it --rm -v `pwd`:/movesense:delegated movesense/sensor-build-env:latest

Windows:

docker run -it --rm -v c:/My/Project/Folder/movesense-device-lib:/movesense:delegated movesense/sensor-build-env:latest

and when docker prompt starts:

cd /movesense
mkdir myBuild
cd myBuild

Now, run the CMake (needs to be done only once unless you add files to the project). It's possible to build both the debug and release version. In both cases the command will contain the following:

cmake -G Ninja -DMOVESENSE_CORE_LIBRARY=../MovesenseCoreLib/ -DCMAKE_TOOLCHAIN_FILE=../MovesenseCoreLib/toolchain/gcc-nrf52.cmake <sample_directory>

But to build a release version it's neccessary to specify the CMAKE_BUILD_TYPE option with the Release value:

cmake -G Ninja -DMOVESENSE_CORE_LIBRARY=../MovesenseCoreLib/ -DCMAKE_TOOLCHAIN_FILE=../MovesenseCoreLib/toolchain/gcc-nrf52.cmake -DCMAKE_BUILD_TYPE=Release <sample_directory>

Note that the means the relative path to the CMakeLists.txt file of the application desired to be built. For example: ../samples/hello_world_app

After that only the last step remains:

ninja pkgs

The created Movesense_combined.hex and the DFU packages can be found in the same directory.

Build commands (Sensor Simulator)

Starting on Movesense device library v1.7.0 it is possible to compile and run your sensor software in the Sensor Simulator. For more info, see the Sensor Simulator -document. To build the Movesense software for Sensor Simulator, clone the repository like above and create a build directory: 

cd movesense-device-lib
mkdir simuBuild
cd simuBuild

Now create the Visual Studio solution 2017 using the CMake: 

cmake -G "Visual Studio 15 2017" -DMOVESENSE_CORE_LIBRARY=../MovesenseCoreLib/ <sample_directory>

To build a release version, specify the CMAKE_BUILD_TYPE option with the Release value: 

cmake -G "Visual Studio 15 2017" -DMOVESENSE_CORE_LIBRARY=../MovesenseCoreLib/ -DCMAKE_BUILD_TYPE=Release <sample_directory>

Note that the means the relative path to the CMakeLists.txt file of the application desired to be built. For example: ../samples/blinky_app

The cmake will generate the Visual Studio solution-file (Project.sln) in the build directory. Just open it with the Visual Studio IDE, select "Movesense" project as a "Startup project" and "Debug" it.

How to update the sensor over Bluetooth

Because the Bluetooth stack (Softdevice) and bootloader have been updated, the first update of a sensor from 1.9.x (or older) to 2.0 has to be done with a DFU packet that contains a bootloader. These are recognizable by the filename that ends with _w_bootloader.zip. After the 2.0 bootloader has been installed, the application can be changed with the smaller "non-bootloader" DFU packet.

Also: The new SoftDevice requires the use of the latest nrf DFU library for Android / iOS. The updated Showcase apps (Android: 1.9.8, iOS: 1.0.5) are available in the usual places (bitbucket Downloads or Apple store).

NOTE: It is not possible to downgrade the sensor back to 1.9 series except with the programming jig!

How to flash the sensor with the programming jig

The updated bootloader has changed the way that the sensor is flashed, so the old piecemal flashing (bootloader, softdevice, application) will not work. Instead the hex files are merged in a single file "Movesense_combined.hex".

In Windows and Mac the flashing can be performed from the separate (non-docker) terminal window by running the following command from the shared build folder:

nrfjprog -f nrf52 --sectoranduicrerase --program Movesense_combined.hex --reset

NOTE: The old Movesense.hex and Movesense_w_settings.hex -files are no longer needed or used. The build process still leaves them around, but you should not use them for anything.

The flashing command ninja flash, only works if the programming jig is attached to the computer that the command is run. In the new build system that "computer" is the virtual computer that runs the docker image. Attaching USB port to docker VM is possible in Linux but not in Windows or Mac. For instructions on how to attach USB to docker VM in linux, see here.

Description of main components

App.cpp

#include "movesense.h"

Movesense.h contains necessary macros and definitions.

MOVESENSE_APPLICATION_STACKSIZE(1024)

You can define the application stack size. If you do not know how it works, do not change it.

MOVESENSE_PROVIDERS_BEGIN(0)
MOVESENSE_PROVIDERS_END(0)

MOVESENSE_PROVIDERS_BEGIN and MOVESENSE_PROVIDERS_END contains the definitions of the new providers. See "Creating own data provider" for more informations.

MOVESENSE_FEATURES_BEGIN()

The Movesense library has possibility to change the state of some providers and configure them. It can help you save some extra memory for your application.

// Explicitly enable or disable Movesense framework core modules.
// List of modules and their default state is found in documentation
OPTIONAL_CORE_MODULE(DataLogger, true)
OPTIONAL_CORE_MODULE(Logbook, true)
OPTIONAL_CORE_MODULE(LedService, true)
OPTIONAL_CORE_MODULE(IndicationService, true)
OPTIONAL_CORE_MODULE(BleService, true)
OPTIONAL_CORE_MODULE(EepromService, true)
OPTIONAL_CORE_MODULE(BypassService, false)

// NOTE: It is inadvisable to enable both Logbook/DataLogger and EepromService without 
// explicit definition of Logbook memory area (see LOGBOOK_MEMORY_AREA macro in movesense.h and eeprom_logbook_app).
// Default setting is for Logbook to use the whole EEPROM memory area. 
// LOGBOOK_MEMORY_AREA(offset, size);

This part is connected to optional modules. You can disable or enable them. To see all Optional modules and default values for them you can see this document.

APPINFO_NAME("Sample Plain");
APPINFO_VERSION("1.0.0");
APPINFO_COMPANY("Movesense");

It is dedicated part for your application. You can easily check what is installed on the Movesense and version of your application.

Check /Info and /Info/App API's.

BLE_COMMUNICATION(true)

BLE_COMMUNICATION should be always true.

MOVESENSE_FEATURES_END()

app_root.yaml

This yaml file contains configuration for the Whiteboard which is a part of the Movesense. You should not change the values if you do not understand them - it can change the stability of the platform.

# Type of the document
wbres:
  version: "2.0"
  type: "root"

# Execution context definitions
executionContexts:
  application:
    numberOfDpcs: 8
    numberOfRequests: 20
    numberOfResponses: 25
    externalThread: true # we run this execution context in main thread
    stackSize: 768
    priority: normal
  meas:
    numberOfDpcs: 9
    numberOfRequests: 25
    numberOfResponses: 10
    stackSize: 768
    priority: normal

Example Project

Suggested way of working with our library is not mandatory, but it helps to setup environment and to create first project.

Setting up the project

  1. Create git repository: 
  $ mkdir myproject  
  $ cd myproject  
  $ git init
  1. Add submodule: 
  $ git submodule add git@bitbucket.org:movesense/movesense-device-lib.git movesense-device-lib --depth 1 --force
  1. Copy plain application sample to main directory: 
  $ cp -R movesense-device-lib/samples/plain_app/* ./

Or optionally on mingw: 

  $ cp movesense-device-lib/samples/plain_app/* ./ -R
  1. Compile
  2. create and enter build dir:
    $ mkdir builddir
    $ cd builddir
  3. generate ninja files:
    $ cmake -G "Ninja" -DCMAKE_TOOLCHAIN_FILE=../movesense-device-lib/MovesenseCoreLib/toolchain/gcc-nrf52.cmake -DMOVESENSE_CORE_LIBRARY=../movesense-device-lib/MovesenseCoreLib ../ -DCMAKE_BUILD_TYPE=Debug ../

  4. run ninja to build DFU and hex files:
    $ ninja

  5. Test
    Run ninja dfupkg and use the resulting zip file to update the firmware on movesense sensor with your phone (DFU).
    Alternatively, run ninja pkgs to create both DFU file as well as hex files to use when flashing the sensor using the Jig.

  6. Great job - your project is now ready for development!

Creating own data provider

It is good practise to calculate on the Movesense to avoid additional BLE communication. So if you want to do some application which ex. is counting steps you should put the algorithm on the Movesense and send only result of the calculation to the mobile phone.

Creating API yaml file

The first step is to create the API yaml file. You can see the sample apps and the Movesense API.

API below contains only one path and only GET function which will be returning always value.

Test.yaml

swagger: '2.0'

info:
  version: "0.0.0"
  title: Test API
  description: |
    Description
  termsOfService: http://xxxxx.com/
  contact:
    name: ABCD Company
    url: http://COMPANYABCD.com

# Paths
paths:
  /Sample/Test:
    get:
      description: |
        Test function returning always 1
      responses:
        200:
          schema:
            description: New value
            $ref: '#/definitions/Test'

definitions:
  Test:
    required:
      - Value
    properties:
      Value:
        description: Some description
        type: integer
        format: uint8

Changing app_root.yaml

apis:
  Test.*:
    apiId: 100
    defaultExecutionContext: meas

Simple TestService Implementation

TestService.hpp

#pragma once

#include "app-resources/resources.h"
#include <whiteboard/LaunchableModule.h>
#include <whiteboard/ResourceProvider.h>

class TestService FINAL : private whiteboard::ResourceProvider,
                          public whiteboard::LaunchableModule

Service class should extend whiteboard::ResourceProvider and whiteboard::LaunchableModule classes.

{
public:
    static const char* const LAUNCHABLE_NAME;
    TestService();
    ~TestService();

private:
    virtual bool initModule() OVERRIDE;
    virtual void deinitModule() OVERRIDE;
    virtual bool startModule() OVERRIDE { mModuleState = WB_RES::ModuleStateValues::STARTED; return true;}
    virtual void stopModule() OVERRIDE { mModuleState = WB_RES::ModuleStateValues::STOPPED; }

It is a good practise to OVERRIDE all state functions. You can check implementation of initModule and deinitModule in TestService.cpp file.

    virtual void onGetRequest(const whiteboard::Request& request,
                              const whiteboard::ParameterList& parameters) OVERRIDE;
};

onGetRequest is called when you will request data from the Movesense ( Sample/Test GET from yaml file). You can check other functions like onPutRequest, onSubscribe, ... in the Whiteboard documentation.

TestService.cpp

#include "movesense.h"
#include "TestService.hpp"
#include "app-resources/resources.h"

const char* const TestService::LAUNCHABLE_NAME = "TestSvc";

static const whiteboard::LocalResourceId sProviderResources[] = {
    WB_RES::LOCAL::SAMPLE_TEST::LID,
};

TestService::TestService()
    : ResourceProvider(WBDEBUG_NAME(__FUNCTION__), WB_RES::LOCAL::SAMPLE_TEST::EXECUTION_CONTEXT),
      LaunchableModule(LAUNCHABLE_NAME, WB_RES::LOCAL::SAMPLE_TEST::EXECUTION_CONTEXT)
{}

TestService::~TestService()
{}

bool TestService::initModule()
{
    if (registerProviderResources(sProviderResources) != whiteboard::HTTP_CODE_OK)
    {
        return false;
    }

    mModuleState = WB_RES::ModuleStateValues::INITIALIZED;
    return true;
}

void TestService::deinitModule()
{
    unregisterProviderResources(sProviderResources);
    mModuleState = WB_RES::ModuleStateValues::UNINITIALIZED;
}


void TestService::onGetRequest(const whiteboard::Request& request,
                                     const whiteboard::ParameterList& parameters)
{

    if (mModuleState != WB_RES::ModuleStateValues::STARTED)
    {
        return returnResult(request, wb::HTTP_CODE_SERVICE_UNAVAILABLE);
    }

    switch (request.getResourceConstId())
    {
    case WB_RES::LOCAL::SAMPLE_TEST::ID:
    {
        WB_RES::Test test;
        test.value = 1;
        return returnResult(request, whiteboard::HTTP_CODE_OK, ResponseOptions::Empty, test);
    }

    break;

    default:
        return returnResult(request, whiteboard::HTTP_CODE_NOT_FOUND);
    }
}

Update App.cpp

The last change necessary to complete our simple app.

#include "TestService.hpp"

MOVESENSE_PROVIDERS_BEGIN(1)
MOVESENSE_PROVIDER_DEF(TestService)
MOVESENSE_PROVIDERS_END(1)

MOVESENSE_PROVIDERS_BEGIN and MOVESENSE_PROVIDERS_END should be incremented and the new service added.