Unverified Commit 236d10fc authored by Ken A. Redergård's avatar Ken A. Redergård Committed by GitHub
Browse files

Consolidate SoftDevice APIs (#176)

Changes:
* Consolidate SoftDevice API v2, v3, v5 and v6

We've had feedback from users telling us that it is not easy to
know what version of pc-ble-driver to use towards a given SoftDevice
API version.

We have also experienced that it is time consuming when maintaining
the pc-ble-driver project to have separate releases of pc-ble-driver for
different major versions.

This commit starts a strategy where we release all
SoftDevice API versions in every release of pc-ble-driver.

It also reuse parts of the codecs from the nRF5 SDK for SoftDevice
API v3 and onwards since parts of those are backwards compatible.

* Port connectivity firmware build script to cmake (#136, ++)

New build system for connectivity firmware
The previous way of building the connectivity firmware was a lot of manual steps supported by Windows .bat files and Cygwin/msys bash scripts.

The new build system has the following changes:
- uses a directory structure convention to auto...
parent 23ff3ced
---
Language: Cpp
AccessModifierOffset: -2
AlignAfterOpenBracket: Align
AlignConsecutiveAssignments: true
AlignConsecutiveDeclarations: false
AlignEscapedNewlines: Right
AlignOperands: true
AlignTrailingComments: true
AllowAllParametersOfDeclarationOnNextLine: true
AllowShortBlocksOnASingleLine: false
AllowShortCaseLabelsOnASingleLine: false
AllowShortFunctionsOnASingleLine: None
AllowShortIfStatementsOnASingleLine: false
AllowShortLoopsOnASingleLine: false
AlwaysBreakAfterDefinitionReturnType: None
AlwaysBreakAfterReturnType: None
AlwaysBreakBeforeMultilineStrings: false
AlwaysBreakTemplateDeclarations: false
BinPackArguments: true
BinPackParameters: true
BraceWrapping:
AfterClass: true
AfterControlStatement: true
AfterEnum: false
AfterFunction: true
AfterNamespace: false
AfterObjCDeclaration: false
AfterStruct: true
AfterUnion: false
AfterExternBlock: false
BeforeCatch: true
BeforeElse: true
IndentBraces: false
SplitEmptyFunction: false
SplitEmptyRecord: false
SplitEmptyNamespace: false
BreakBeforeBinaryOperators: None
BreakBeforeBraces: Custom
BreakBeforeInheritanceComma: false
BreakBeforeTernaryOperators: true
BreakConstructorInitializersBeforeComma: true
BreakConstructorInitializers: BeforeColon
BreakAfterJavaFieldAnnotations: false
BreakStringLiterals: true
ColumnLimit: 100
CommentPragmas: '^ IWYU pragma:'
CompactNamespaces: false
ConstructorInitializerAllOnOneLineOrOnePerLine: false
ConstructorInitializerIndentWidth: 4
ContinuationIndentWidth: 4
Cpp11BracedListStyle: true
DerivePointerAlignment: false
DisableFormat: false
ExperimentalAutoDetectBinPacking: false
FixNamespaceComments: true
ForEachMacros:
- foreach
- Q_FOREACH
- BOOST_FOREACH
IncludeBlocks: Preserve
IncludeCategories:
- Regex: '^"(llvm|llvm-c|clang|clang-c)/'
Priority: 2
- Regex: '^(<|"(gtest|gmock|isl|json)/)'
Priority: 3
- Regex: '.*'
Priority: 1
IncludeIsMainRegex: '(Test)?$'
IndentCaseLabels: true
IndentPPDirectives: None
IndentWidth: 4
IndentWrappedFunctionNames: false
JavaScriptQuotes: Leave
JavaScriptWrapImports: true
KeepEmptyLinesAtTheStartOfBlocks: false
MacroBlockBegin: ''
MacroBlockEnd: ''
MaxEmptyLinesToKeep: 1
NamespaceIndentation: None
ObjCBlockIndentWidth: 2
ObjCSpaceAfterProperty: false
ObjCSpaceBeforeProtocolList: true
PenaltyBreakAssignment: 2
PenaltyBreakBeforeFirstCallParameter: 19
PenaltyBreakComment: 300
PenaltyBreakFirstLessLess: 120
PenaltyBreakString: 1000
PenaltyExcessCharacter: 1000000
PenaltyReturnTypeOnItsOwnLine: 60
PointerAlignment: Right
RawStringFormats:
- Delimiter: pb
Language: TextProto
BasedOnStyle: google
ReflowComments: true
SortIncludes: true
SortUsingDeclarations: true
SpaceAfterCStyleCast: false
SpaceAfterTemplateKeyword: true
SpaceBeforeAssignmentOperators: true
SpaceBeforeParens: ControlStatements
SpaceInEmptyParentheses: false
SpacesBeforeTrailingComments: 1
SpacesInAngles: false
SpacesInContainerLiterals: true
SpacesInCStyleCastParentheses: false
SpacesInParentheses: false
SpacesInSquareBrackets: false
Standard: Cpp11
TabWidth: 8
UseTab: Never
---
Checks: "-*,\
-llvm-header-guard,\
-llvm-include-order,\
-llvm-namespace-comment,\
-readability-else-after-return,\
-misc-macro-parentheses,\
-clang-analyzer-alpha.core.CastToStruct,\
-modernize-raw-string-literal,\
-cppcoreguidelines-pro-bounds-array-to-pointer-decay,\
-cppcoreguidelines-pro-bounds-constant-array-index,\
-cppcoreguidelines-pro-bounds-pointer-arithmetic,\
-cppcoreguidelines-pro-type-member-init,\
-cppcoreguidelines-pro-type-reinterpret-cast,\
-cppcoreguidelines-pro-type-vararg,\
-google-readability-namespace-comments,\
-google-readability-braces-around-statements,-readability-braces-around-statements,\
-google-readability-todo,\
-google-runtime-int,\
-google-runtime-references,\
"
...
......@@ -5,6 +5,11 @@ _build
*.pyc
**/build
/sdk/
build*/
# Temporary files
*.bak
*.TMP
# Object files
*.o
......
This diff is collapsed.
cmake_minimum_required(VERSION 3.11)
project(pc-ble-driver)
include (cmake/pc-ble-driver.cmake)
include(cmake/pc-ble-driver.cmake)
include(TestBigEndian)
TEST_BIG_ENDIAN(IS_BIG_ENDIAN)
if(IS_BIG_ENDIAN)
message(FATAL_ERROR "Protocol implementation does not support big endian platforms.")
endif()
# Common source files
file(GLOB LIB_BASE_C_SRC_FILES "src/common/*.c")
......@@ -22,11 +28,31 @@ else()
file(GLOB LIB_PLATFORM_CPP_SRC_FILES "src/common/platform/linux/*.cpp")
endif()
set(PC_BLE_DRIVER_DEFAULT_VERSION "4.0.0")
set(PC_BLE_DRIVER_CONNECTIVITY_DEFAULT_VERSION "0.0.0")
if(NOT DEFINED PC_BLE_DRIVER_VERSION)
message(STATUS "PC_BLE_DRIVER_VERSION not specified, setting it to ${PC_BLE_DRIVER_DEFAULT_VERSION}")
set(PC_BLE_DRIVER_VERSION "${PC_BLE_DRIVER_DEFAULT_VERSION}")
endif()
# Add connectivity firmware building
if(NOT DEFINED CONNECTIVITY_VERSION)
message(STATUS "CONNECTIVITY_VERSION not specified, using ${PC_BLE_DRIVER_CONNECTIVITY_DEFAULT_VERSION}")
set(CONNECTIVITY_VERSION "${PC_BLE_DRIVER_CONNECTIVITY_DEFAULT_VERSION}" CACHE STRING "" FORCE)
else()
set(CONNECTIVITY_VERSION "${CONNECTIVITY_VERSION}" CACHE STRING "" FORCE)
endif()
# SDK source files, different per API version
# Newer codecs from nRF5 SDK are backwards compatible to SoftDevice API v3
file(GLOB_RECURSE LIB_NEWER_SDK_API_COMMON_C_SRC_FILES "src/sd_api_common/sdk/*.c")
foreach(SD_API_VER ${SD_API_VERS})
string(TOLOWER ${SD_API_VER} SD_API_VER_L)
file(GLOB_RECURSE LIB_SDK_${SD_API_VER}_C_SRC_FILES "src/${SD_API_VER_L}/sdk/*.c")
file(GLOB_RECURSE LIB_SDK_${SD_API_VER}_CPP_SRC_FILES "src/${SD_API_VER_L}/sdk/*.cpp")
file(GLOB_RECURSE LIB_SDK_${SD_API_VER}_CPP_SRC_FILES "src/${SD_API_VER_L}/*.cpp")
endforeach(SD_API_VER)
# Set C, CPP and platform source file groups and properties
......@@ -36,11 +62,19 @@ foreach(SD_API_VER ${SD_API_VERS})
${LIB_TRANSPORT_C_SRC_FILES}
)
if(SD_API_VER STRGREATER "SD_API_V2")
list(APPEND LIB_${SD_API_VER}_C_SRC_FILES ${LIB_NEWER_SDK_API_COMMON_C_SRC_FILES})
endif()
#message(STATUS "SD: ${SD_API_VER}: C_SRC: ${LIB_${SD_API_VER}_C_SRC_FILES}")
set(LIB_${SD_API_VER}_CPP_SRC_FILES ${LIB_BASE_CPP_SRC_FILES}
${LIB_SDK_${SD_API_VER}_CPP_SRC_FILES}
${LIB_TRANSPORT_CPP_SRC_FILES}
)
#message(STATUS "SD: ${SD_API_VER}: CPP_SRC: ${LIB_${SD_API_VER}_CPP_SRC_FILES}")
# Force .c files to be compiled with the C++ compiler
if(NOT APPLE)
set_source_files_properties(
......@@ -53,25 +87,16 @@ endforeach(SD_API_VER)
set(LIB_PLATFORM_SRC_FILES ${LIB_PLATFORM_C_SRC_FILES} ${LIB_PLATFORM_CPP_SRC_FILES})
if(WIN32)
# Disable CRT Warnings with Visual Studio
set_source_files_properties(
${LIB_PLATFORM_C_SRC_FILES}
PROPERTIES
COMPILE_FLAGS "${CMAKE_C_FLAGS} -D_CRT_SECURE_NO_WARNINGS"
)
set_source_files_properties(
${LIB_PLATFORM_CPP_SRC_FILES}
PROPERTIES
COMPILE_FLAGS "${CMAKE_CXX_FLAGS} -D_CRT_SECURE_NO_WARNINGS"
)
endif()
# Add common compiler definitions
add_definitions(
-DSD_RPC_EXPORTS
-DHCI_LINK_CONTROL # Adds support for Link Control packets according to the HCI standard
)
if(WIN32)
add_definitions(-D_CRT_SECURE_NO_WARNINGS)
endif()
# Add libraries
foreach(SD_API_VER ${SD_API_VERS})
# Object library, from which both shared and static will be built
......@@ -86,30 +111,45 @@ foreach(SD_API_VER ${SD_API_VERS})
endforeach(SD_API_VER)
# Set common include directories
find_path(ASIO_INCLUDE_DIR asio.hpp)
include_directories(
include/common
include/common/sdk_compat
include/common/internal
include/common/internal/transport
# Include boost as a system include so that the compiler doesn't nag about issues in boost header files
SYSTEM ${Boost_INCLUDE_DIRS}
SYSTEM ${ASIO_INCLUDE_DIR}
)
# Set per-SD API version include directories and compiler definitions
foreach(SD_API_VER ${SD_API_VERS})
string(TOLOWER ${SD_API_VER} SD_API_VER_L)
target_include_directories (${PC_BLE_DRIVER_${SD_API_VER}_OBJ_LIB} PRIVATE
src/${SD_API_VER_L}/sdk/components/libraries/util
src/${SD_API_VER_L}/sdk/components/serialization/application/codecs/common
src/${SD_API_VER_L}/sdk/components/serialization/application/codecs/s130/serializers
src/${SD_API_VER_L}/sdk/components/serialization/application/codecs/s132/serializers
src/${SD_API_VER_L}/sdk/components/serialization/application/codecs/ble/serializers
src/${SD_API_VER_L}/sdk/components/serialization/common
src/${SD_API_VER_L}/sdk/components/serialization/common/struct_ser/s130
src/${SD_API_VER_L}/sdk/components/serialization/common/struct_ser/s132
src/${SD_API_VER_L}/sdk/components/serialization/common/struct_ser/ble
src/${SD_API_VER_L}/sdk/components/softdevice/s132/headers
)
# Newer codecs from nRF5 SDK are backwards compatible to SoftDevice API v3
if(SD_API_VER STRGREATER "SD_API_V2")
target_include_directories (${PC_BLE_DRIVER_${SD_API_VER}_OBJ_LIB} SYSTEM PRIVATE
src/sd_api_common/sdk/components/libraries/util
src/${SD_API_VER_L}/sdk/components/serialization/application/codecs/common
src/${SD_API_VER_L}/sdk/components/serialization/application/codecs/s132/serializers
src/${SD_API_VER_L}/sdk/components/serialization/application/codecs/ble/serializers
src/sd_api_common/sdk/components/serialization/common
src/sd_api_common/sdk/components/serialization/common/struct_ser/ble
src/${SD_API_VER_L}/sdk/components/softdevice/s132/headers
src/${SD_API_VER_L}/sdk/components/softdevice/s140/headers
src/${SD_API_VER_L}
)
else()
target_include_directories (${PC_BLE_DRIVER_${SD_API_VER}_OBJ_LIB} SYSTEM PRIVATE
src/${SD_API_VER_L}/sdk/components/libraries/util
src/${SD_API_VER_L}/sdk/components/serialization/application/codecs/common
src/${SD_API_VER_L}/sdk/components/serialization/application/codecs/s130/serializers
src/${SD_API_VER_L}/sdk/components/serialization/common
src/${SD_API_VER_L}/sdk/components/serialization/common/struct_ser/s130
# S132 and S130 headers are the same
src/${SD_API_VER_L}/sdk/components/softdevice/s132/headers
)
endif()
# Provide the NRF_SD_BLE_API_VERSION macro to each variant
string(REGEX MATCH "[0-9]+$" _SD_API_VER_NUM "${SD_API_VER}")
set(SD_API_VER_COMPILER_DEF_NUM "-D${SD_API_VER_COMPILER_DEF}=${_SD_API_VER_NUM}")
......@@ -139,6 +179,14 @@ endforeach(SD_API_VER)
# Add tests
add_subdirectory(test)
# Add examples
add_subdirectory(examples)
include (cmake/clang-dev-tools.cmake)
# Add install target
include(cmake/install-target.cmake)
if(COMPILE_CONNECTIVITY)
add_subdirectory(hex)
endif()
include (cmake/clang-dev-tools.cmake)
## SoftDevice and IC support
The libraries generated are compatible with the following SoftDevice API versions and nRF5x ICs:
* SoftDevice s130 API version 2: `s130_nrf51_2.x.x` (nRF51 and nRF52 series ICs)
* SoftDevice s132 API version 5: `s132_nrf52_5.x.x` (only for nRF52 series ICs)
The .hex files included in the `hex/sd_api_v<x>` folder include both the SoftDevice and the connectivity firmware required to communicate with it.
## Operating system support
* Windows (XP, 7, 8, 8.1, 10) 32 and 64-bit
* GNU/Linux (Ubuntu tested) 32 and 64-bit
* macOS (OS X) 32 and 64-bit
## Hardware setup
### Installing drivers and tools
This communication library works over any kind of serial port (UART), but it is most often used over a Segger J-Link USB CDC UART.
To set up the required J-Link drivers simply download and install the version matching you operating system:
* [Segger J-Link Downloads](https://www.segger.com/jlink-software.html)
Additionally to flash the connectivity firmware you will need `nrfjprog` which is bundled with the nRF5x Command-Line Tools, which can be downloaded from:
* [nRF5x Command-Line Tools for Windows](https://www.nordicsemi.com/eng/nordic/Products/nRF51822/nRF5x-Command-Line-Tools-Win32/33444)
* [nRF5x Command-Line Tools for Linux 32-bit](https://www.nordicsemi.com/eng/nordic/Products/nRF51822/nRF5x-Command-Line-Tools-Linux32/52615)
* [nRF5x Command-Line Tools for Linux 64-bit](https://www.nordicsemi.com/eng/nordic/Products/nRF51822/nRF5x-Command-Line-Tools-Linux64/51386)
* [nRF5x Command-Line Tools for OS X](https://www.nordicsemi.com/eng/nordic/Products/nRF51822/nRF5x-Command-Line-Tools-OSX/53402)
### Flashing the connectivity firmware
To use this library you will need to flash the connectivity firmware on a nRF5x IC
Once you have installed the nRF5x Command-Line Tools, you can erase and program the IC:
$ nrfjprog -f NRF5<x> -e
$ nrfjprog -f NRF5<x> --program hex/sd_api_v<x>/connectivity_<ver>_<baudrate>_with_s13<v>_<a>.<b>.<c>.hex
### J-Link USB CDC serial ports
After you have installed the required drivers and connected a J-Link enabled board (such as the Nordic Development Kits) the port should appear automatically
#### Windows
The serial port will appear as `COMxx`. Simply check the "Ports (COM & LPT)" section in the Device Manager.
#### Ubuntu Linux
The serial port will appear as `/dev/ttyACMx`. By default the port is not accessible to all users. Type the command below to add your user to the `dialout` group to give it access to the serial port. Note that re-login is required for this to take effect.
sudo usermod -a -G dialout <username>
To prevent the modemmanager service from trying to connect to the CDC ACM serial port:
systemctl stop ModemManager.service
systemctl disable ModemManager.service
#### macOS (OS X)
The serial port will appear as `/dev/tty.usbmodemXXXX`.
**IMPORTANT NOTE**
On macOS (OS X) there is a known issue with the Segger J-Link firmware (that runs on the Debug probe on the board) related to USB packet sizes. This results in the timeout error `Failed to open nRF BLE Driver. Error code: 0x0D` when the serial port is attempted to be opened.
There are two ways to solve this issue:
1. Use the Segger firmware, but disable the Mass Storage Device (MSD) feature. Instructions are available [here](https://wiki.segger.com/index.php?title=J-Link-OB_SAM3U).
2. Replace the firmware on the Debug probe with the mbed DAPLink firmware:
- Enter bootloader mode by powering off the nRF5 Development Kit and then pressing IF BOOT/RESET while you power on the kit.
- Drag and drop the [nrf5x_osx_fix.bin](https://github.com/NordicSemiconductor/pc-ble-driver/blob/master/tools/nrf5x_osx_fix.bin) file into the BOOTLOADER mass storage device.
If you want to revert back to the Segger firmware you will have to download the it from [this location](http://www.nordicsemi.com/eng/nordic/Products/nRF51-DK/nRF5x-OB-JLink-IF/52276)
## Compiling the connectivity .hex files
Precompiled connectivity firmware are provided and can be used with standard Nordic Development Kits. The .hex files are available in the `hex/sd_api_v<x>` folder. They include the SoftDevice and the connectivity application.
You only need to recompile the connectivity application if you want to run it on a custom board. You can use the `hex/sd_api_v<x>/bootstrap_sd_api_v<X>.sh` script to download and patch the nRF SDK and the application with ease. Using this scripts, the steps 1 and 2 below are done automatically:
1. [Download the nRF SDK 11 or 14](https://developer.nordicsemi.com/nRF5_SDK/) (depending on the SoftDevice API you want to use) and unzip `nRF5_SDK_<x>.<y>.<z>_<sha>.zip`
2. Apply the patch `hex/sd_api_v<x>/SDK<ver>_connectivity.patch` from the unzipped SDK folder (e.g. `git apply -p1 --ignore-whitespace /repos/pc-ble-driver/hex/sd_api_v2/sdk110_connectivity.patch`)
3. Open the connectivity project `<sdk>/examples/ble_central_and_peripheral/ble_connectivity/pca100<xx>/ser_s13<x>_hci`
4. Compile it using the the compiler of your choice
5. Merge the built connectivity hex file with the corresponding SoftDevice hex file (e.g. `mergehex -m connectivity.hex softdevice.hex -o connectivity_with_softdevice.hex`)
## Building Boost
The Boost static libraries required by this drivers must be built before you can build any of the
repositories above that depend on pc-ble-driver.
### Obtain the Boost source code
Note: This step is not required for macOS (OS X).
Use the following link to download the Boost source code:
* [Boost](http://www.boost.org/users/download) (>=1.67.0)
- Download and extract Boost to a folder of your choice.
- Set the environment variable `BOOST_ROOT` to the path where you have extracted Boost.
For example on Windows assuming you've unpacked Boost in `c:\boost\boost_1_xx_y`:
setx BOOST_ROOT "c:\boost\boost_1_xx_y"
And on Linux or macOS (OS X) assuming you've unpacked Boost in `~/boost/boost_1_xx_y`:
export BOOST_ROOT="~/boost/boost_1_xx_y"
#### Windows
Install Microsoft Visual Studio. The following versions supported are:
* Visual Studio 2015 (MSVC 14.0)
Open a Microsoft Visual Studio Command Prompt and issue the following commands:
> cd %BOOST_ROOT%
> bootstrap.bat
> b2 toolset=msvc-<VV.V> address-model=<32,64> link=static --with-thread --with-system --with-regex --with-date_time --with-chrono
**Note**: If you intend to build a 64-bit version of Boost, you might need to open a 64-bit command prompt such as
"Visual Studio 2015 x86 x64 Cross Tools Command Prompt" or similar, or run `vcvarsall.bat x86_amd64` or `setenv.cmd" /Release /x64`.
**Note**: Refer to the [compiler list](http://www.boost.org/build/doc/html/bbv2/reference/tools.html#bbv2.reference.tools.compilers) of the Boost documentation
to find the version of the MSVC that you need to provide using the `toolset=` option.
**Note**: Select 32 or 64-bit with the `address-model=` option.
**Note**: Use `dumpbin /headers <file>` to check whether a particular object file is 32 or 64-bit.
##### Examples
Build 64-bit Boost with Visual Studio 2015:
> b2 toolset=msvc-14.0 address-model=64 link=static --with-thread --with-system --with-regex --with-date_time --with-chrono
##### Side-by-side 32 and 64-bit versions
If you want to be able to have both the 32 and 64-bit versions of Boost available, add `--stagedir=./stage/x86_32` when building the 32-bit version and `--stagedir=./stage/x86_64` when building the 64-bit one, and they will be placed in `stage\x86_32\lib` and `stage\x86_64\lib` respectively. Later on you when building repositories that depend on this one, you will be able to point CMake the correct version of the libraries by using `-DBOOST_LIBRARYDIR="c:\boost\boost_1_xx_y\stage\x86_XX\lib`.
#### Ubuntu Linux
Install the required packages to build Boost:
sudo apt-get install git make gcc g++
Additionally if you want to build non-native binaries (for example 32-bit binaries on a 64-bit Ubuntu installation):
sudo apt-get install gcc-multilib
Open a terminal window and issue the following commands:
$ cd $BOOST_ROOT
$ ./bootstrap.sh
$ ./b2 toolset=gcc cxxflags=-fPIC cflags=-fPIC address-model=<32,64> link=static --with-thread --with-system --with-regex --with-date_time --with-chrono
**Note**: Select 32 or 64-bit with the `address-model=` option.
**Note**: Use `objdump -f <file>` to check whether a particular object file is 32 or 64-bit.
##### Side-by-side 32 and 64-bit versions
If you want to be able to have both the 32 and 64-bit versions of Boost available, add `--stagedir=./stage/x86_32` when building the 32-bit version and `--stagedir=./stage/x86_64` when building the 64-bit one, and they will be placed in `stage/x86_32` and `stage/x86_64` respectively. Later on you when building repositories that depend on this one, you will be able to point CMake the correct version of the libraries by using `-DBOOST_LIBRARYDIR="~/boost/boost_1_xx_y/stage/x86_XX/lib`.
#### macOS (OS X) 10.11 and later
Install Xcode from the App Store.
The simplest way to install Boost is to use Homebrew. If you don't have Homebrew installed simply run on a terminal:
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
If you already have Homebrew installed, make sure it's up to date with:
$ brew update
$ brew upgrade
Once Homebrew is installed you can use the `brew` command on a terminal to install boost:
$ brew install boost
This will download the boost source and compile it, so it might take a while.
## Compiling pc-ble-driver from source
Assuming that you have built the Boost libraries and installed the tools required to do so [as described above](#building-boost), you can now build the shared library.
### Dependencies
To build this project you will need the following tools:
* [CMake](https://cmake.org/) (>=3.11)
* A C/C++ toolchain (should already have been installed to build Boost)
See the following sections for platform-specific instructions on the installation of the dependencies.
#### Windows
* Install the latest CMake stable release by downloading the Windows Installer from:
[CMake Downloads](https://cmake.org/download/)
Open a Microsoft Visual Studio Command Prompt and issue the following from the root folder of the repository:
> cd build
> cmake -G "Visual Studio 14 <Win64>" <-DBOOST_LIBRARYDIR="<Boost libs path>>" ..
> msbuild ALL_BUILD.vcxproj </p:Configuration=<CFG>>
**Note**: Add `Win64` to the `-G` option to build a 64-bit version of the driver.
**Note**: Optionally select the location of the Boost libraries with the `-DBOOST_LIBRARYDIR` option.
**Note**: Optionally select the build configuration with the `/p:Configuration=` option. Typically `Debug`, `Release`, `MinSizeRel` and `RelWithDebInfo` are available.
##### Examples
Building for with 64-bit Visual Studio 2015:
> cmake -G "Visual Studio 14" ..
#### Ubuntu Linux
Install cmake:
$ sudo apt-get install cmake
Then change to the root folder of the repository and issue the following commands:
$ cd build
> cmake -G "Unix Makefiles" <-DCMAKE_BUILD_TYPE=<build_type>> <-DARCH=<x86_32,x86_64>> <-DBOOST_LIBRARYDIR="<Boost libs path>>" ..
$ make
**Note**: Optionally Select the build configuration with the `-DCMAKE_BUILD_TYPE` option. Typically `Debug`, `Release`, `MinSizeRel` and `RelWithDebInfo` are available.
**Note**: Optionally select the target architecture (32 or 64-bit) using the `-DARCH` option.
**Note**: Optionally select the location of the Boost libraries with the `-DBOOST_LIBRARYDIR` option.
#### macOS (OS X) 10.11 and later
Install cmake with Homebrew with the `brew` command on a terminal:
$ brew install cmake
Then change to the root folder of the repository and issue the following commands:
$ cd build
$ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE= <build_type> ..
$ make
**Note**: Optionally Select the build configuration with the `-DCMAKE_BUILD_TYPE` option. Typically `Debug`, `Release`, `MinSizeRel` and `RelWithDebInfo` are available.
Deprecation notice. The contents of this file have been moved to [README.md](/README.md)
\ No newline at end of file
# Known Issues
## Windows Issues
#### /dev/null git apply issue
`Git` >= 2.19.0 is required to solve this issue.
#### CreateProcess issue
```
echo Makefile
CreateProcess(NULL,echo Makefile,...)
process_begin: CreateProcess(NULL, echo Makefile, ...) failed.
Putting child 01DD8B10 (_build) PID 31536216 on the chain.
Live child 01DD8B10 (_build) PID 31536216
make (e=2): The system cannot find the file specified.
Reaping losing child 01DD8B10 PID 31536216
make: *** [Makefile:323: _build] Error 2
Removing child 01DD8B10 PID 31536216 from chain.
```
This issue is due to having `sh` or `bash` in PATH.
`sh` or `bash` must not be in the PATH.
#### Long paths issue
```
Compiling file: ble_gap_evt_conn.c
../../../../../../components/serialization/connectivity/codecs/ble/serializers/ble_gap_evt_conn.c:46:10: fatal error: conn_ble_gap_sec_keys.h: No such file or directory
#include "conn_ble_gap_sec_keys.h"
^~~~~~~~~~~~~~~~~~~~~~~~~
compilation terminated.
make: *** [../../../../../../components/toolchain/gcc/Makefile.common:272:
```
In the Windows API (with some exceptions discussed in the following paragraphs), the maximum length for a path is MAX_PATH, which is defined as 260 characters. If the path length exceeds MAX_PATH, then it will have this issue.
[See more details here](https://docs.microsoft.com/en-us/windows/desktop/fileio/naming-a-file#paths)
---
## macOS Issues
#### Timeout error related to the SEGGER J-Link firmware
On macOS there is a known issue with the SEGGER J-Link firmware (that runs on the Debug probe on the board) related to USB packet sizes. This results in the timeout error `Failed to open nRF BLE Driver. Error code: 0x0D` when the serial port is attempted to be opened.
There are two ways to solve this issue:
1. Use the SEGGER firmware, but disable the Mass Storage Device (MSD) feature. Instructions are available [here](https://wiki.segger.com/index.php?title=J-Link-OB_SAM3U).
2. Replace the firmware on the Debug probe with the mbed DAPLink firmware:
- Enter bootloader mode by powering off the nRF5 Development Kit and then pressing IF BOOT/RESET while you power on the kit.
- Drag and drop the [nrf5x_osx_fix.bin](https://github.com/NordicSemiconductor/pc-ble-driver/blob/master/tools/nrf5x_osx_fix.bin) file into the BOOTLOADER mass storage device.
If you want to revert back to the SEGGER firmware you will have to download the it from [this location](http://www.nordicsemi.com/eng/nordic/Products/nRF51-DK/nRF5x-OB-JLink-IF/52276)
---
## SEGGER J-Link-OB Issues
#### Data corruption or drops
Due to a known issue in Segger’s J-Link-OB firmware, depending on your operating system and version you might experience data corruption or drops if you use the USB CDC ACM Serial Port with packets larger than 64 bytes. This has been observed on both GNU/Linux and macOS.
To avoid this, you can simply disable the Mass Storage Device by opening: