You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/03/24 21:10:07 UTC
[2/2] incubator-mynewt-site git commit: added introduction to BLE
stack, cleaned adding ble app,
closes pull request #67 which adds cross gsb installation step
added introduction to BLE stack, cleaned adding ble app, closes pull request #67 which adds cross gsb installation step
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/8d34bb42
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/8d34bb42
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/8d34bb42
Branch: refs/heads/asf-site
Commit: 8d34bb4242ca8eb1d48d90e2b5e185f235c7e5b4
Parents: 9159354
Author: aditihilbert <ad...@runtime.io>
Authored: Thu Mar 24 13:09:56 2016 -0700
Committer: aditihilbert <ad...@runtime.io>
Committed: Thu Mar 24 13:09:56 2016 -0700
----------------------------------------------------------------------
mkdocs/search_index.json | 75 ++-
network/ble/ble_intro/index.html | 56 +-
network/ble/ini_stack/ble_ini_intro/index.html | 4 +-
network/ble/nimble_setup/index.html | 550 ++++----------------
os/get_started/cross_tools/index.html | 1 +
sitemap.xml | 26 +-
6 files changed, 191 insertions(+), 521 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/8d34bb42/mkdocs/search_index.json
----------------------------------------------------------------------
diff --git a/mkdocs/search_index.json b/mkdocs/search_index.json
index 303d5f5..e637e9c 100644
--- a/mkdocs/search_index.json
+++ b/mkdocs/search_index.json
@@ -192,7 +192,7 @@
},
{
"location": "/os/get_started/cross_tools/",
- "text": "Installing Cross Tools for ARM\n\n\nThis page shows how to install tools to use some ARM based platforms with\nApache Mynewt.\n\n\n\n\nInstall ARM Cross tools in Mac OS X\n\n\nInstall Tool Chain\n\n\nInstall the PX4 Toolchain and check the version installed. ARM maintains a\npre-built GNU toolchain with a GCC source branch targeted at Embedded ARM\nProcessors, namely Cortex-R/Cortex-M processor families. After installing,\nensure that the symbolic link installed by Homebrew points to the correct\nversion of the debugger.\n\n\n$ brew tap PX4/homebrew-px4\n$ brew update\n$ brew install gcc-arm-none-eabi-49\n$ arm-none-eabi-gcc --version \narm-none-eabi-gcc (GNU Tools for ARM Embedded Processors) 4.9.3 20150529 (release) [ARM/embedded-4_9-branch revision 224288]\nCopyright (C) 2014 Free Software Foundation, Inc.\nThis is free software; see the source for copying conditions. There is NO\nwarranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n
$ ls -al /usr/local/bin/arm-none-eabi-gdb\nlrwxr-xr-x 1 aditihilbert admin 69 Sep 22 17:16 /usr/local/bin/arm-none-eabi-gdb -\n /usr/local/Cellar/gcc-arm-none-eabi-49/20150609/bin/arm-none-eabi-gdb\n\n\n\n\n\nNote:\n If no version is specified, brew will install the latest version\navailable. Mynewt OS will eventually work with multiple versions available,\nincluding the latest releases. However, at present we have tested only with\nthis version and recommend it for getting started. \n\n\n\n\nInstall OpenOCD\n\n\nOpenOCD (Open On-Chip Debugger) is open-source software that allows your\ncomputer to interface with the JTAG debug connector on a variety of boards. A\nJTAG connection lets you debug and test embedded target devices. For more on\nOpenOCD go to \nhttp://openocd.org\n.\n\n\nCurrently, only OpenOCD 0.8.0 is supported.\n\n\n$ brew install open-ocd\n$ which openocd\n/usr/local/bin/openocd\n$ ls -l $(which openocd)\nlrwxr-xr-x 1 \nuser\n admin 36 Sep 17 16:22 /usr/local/b
in/openocd -\n ../Cellar/open-ocd/0.8.0/bin/openocd\n\n\n\n\n\n\n\nInstall ARM cross arm tools for Linux\n\n\nInstall Tool Chain\n\n\nOn a Debian-based Linux distribution, gcc 4.9.3 for ARM can be installed with\napt-get as documented below. The steps are explained in depth at\n\nhttps://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded\n.\n\n\n$ sudo apt-get remove binutils-arm-none-eabi gcc-arm-none-eabi \n$ sudo add-apt-repository ppa:terry.guo/gcc-arm-embedded \n$ sudo apt-get update \n$ sudo apt-get install gcc-arm-none-eabi\n\n\n\n\n\n\n\nInstall OpenOCD\n\n\nOpenOCD (Open On-Chip Debugger) is open-source software that allows your\ncomputer to interface with the JTAG debug connector on a variety of boards. A\nJTAG connection lets you debug and test embedded target devices. For more on\nOpenOCD go to \nhttp://openocd.org\n.\n\n\nIf you are running Ubuntu 15.x, then you are in luck and you can simply run: \n\n\n$ sudo apt-get install openocd \n\n\n\n\n\nFor this project
, you should download the openocd 0.8.0 package from\n\nhttps://launchpad.net/ubuntu/vivid/+source/openocd\n.\nThe direct link to the amd64 build is\n\nhttp://launchpadlibrarian.net/188260097/openocd_0.8.0-4_amd64.deb\n.",
+ "text": "Installing Cross Tools for ARM\n\n\nThis page shows how to install tools to use some ARM based platforms with\nApache Mynewt.\n\n\n\n\nInstall ARM Cross tools in Mac OS X\n\n\nInstall Tool Chain\n\n\nInstall the PX4 Toolchain and check the version installed. ARM maintains a\npre-built GNU toolchain with a GCC source branch targeted at Embedded ARM\nProcessors, namely Cortex-R/Cortex-M processor families. After installing,\nensure that the symbolic link installed by Homebrew points to the correct\nversion of the debugger.\n\n\n$ brew tap PX4/homebrew-px4\n$ brew update\n$ brew install gcc-arm-none-eabi-49\n$ arm-none-eabi-gcc --version \narm-none-eabi-gcc (GNU Tools for ARM Embedded Processors) 4.9.3 20150529 (release) [ARM/embedded-4_9-branch revision 224288]\nCopyright (C) 2014 Free Software Foundation, Inc.\nThis is free software; see the source for copying conditions. There is NO\nwarranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n
$ ls -al /usr/local/bin/arm-none-eabi-gdb\nlrwxr-xr-x 1 aditihilbert admin 69 Sep 22 17:16 /usr/local/bin/arm-none-eabi-gdb -\n /usr/local/Cellar/gcc-arm-none-eabi-49/20150609/bin/arm-none-eabi-gdb\n\n\n\n\n\nNote:\n If no version is specified, brew will install the latest version\navailable. Mynewt OS will eventually work with multiple versions available,\nincluding the latest releases. However, at present we have tested only with\nthis version and recommend it for getting started. \n\n\n\n\nInstall OpenOCD\n\n\nOpenOCD (Open On-Chip Debugger) is open-source software that allows your\ncomputer to interface with the JTAG debug connector on a variety of boards. A\nJTAG connection lets you debug and test embedded target devices. For more on\nOpenOCD go to \nhttp://openocd.org\n.\n\n\nCurrently, only OpenOCD 0.8.0 is supported.\n\n\n$ brew install open-ocd\n$ which openocd\n/usr/local/bin/openocd\n$ ls -l $(which openocd)\nlrwxr-xr-x 1 \nuser\n admin 36 Sep 17 16:22 /usr/local/b
in/openocd -\n ../Cellar/open-ocd/0.8.0/bin/openocd\n\n\n\n\n\n\n\nInstall ARM cross arm tools for Linux\n\n\nInstall Tool Chain\n\n\nOn a Debian-based Linux distribution, gcc 4.9.3 for ARM can be installed with\napt-get as documented below. The steps are explained in depth at\n\nhttps://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded\n.\n\n\n$ sudo apt-get remove binutils-arm-none-eabi gcc-arm-none-eabi \n$ sudo add-apt-repository ppa:terry.guo/gcc-arm-embedded \n$ sudo apt-get update \n$ sudo apt-get install gcc-arm-none-eabi\n$ sudo apt-get install gdb-arm-none-eabi\n\n\n\n\n\n\n\nInstall OpenOCD\n\n\nOpenOCD (Open On-Chip Debugger) is open-source software that allows your\ncomputer to interface with the JTAG debug connector on a variety of boards. A\nJTAG connection lets you debug and test embedded target devices. For more on\nOpenOCD go to \nhttp://openocd.org\n.\n\n\nIf you are running Ubuntu 15.x, then you are in luck and you can simply run: \n\n\n$ sudo apt-get in
stall openocd \n\n\n\n\n\nFor this project, you should download the openocd 0.8.0 package from\n\nhttps://launchpad.net/ubuntu/vivid/+source/openocd\n.\nThe direct link to the amd64 build is\n\nhttp://launchpadlibrarian.net/188260097/openocd_0.8.0-4_amd64.deb\n.",
"title": "Install Cross Tools for ARM"
},
{
@@ -222,7 +222,7 @@
},
{
"location": "/os/get_started/cross_tools/#install-tool-chain_1",
- "text": "On a Debian-based Linux distribution, gcc 4.9.3 for ARM can be installed with\napt-get as documented below. The steps are explained in depth at https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded . $ sudo apt-get remove binutils-arm-none-eabi gcc-arm-none-eabi \n$ sudo add-apt-repository ppa:terry.guo/gcc-arm-embedded \n$ sudo apt-get update \n$ sudo apt-get install gcc-arm-none-eabi",
+ "text": "On a Debian-based Linux distribution, gcc 4.9.3 for ARM can be installed with\napt-get as documented below. The steps are explained in depth at https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded . $ sudo apt-get remove binutils-arm-none-eabi gcc-arm-none-eabi \n$ sudo add-apt-repository ppa:terry.guo/gcc-arm-embedded \n$ sudo apt-get update \n$ sudo apt-get install gcc-arm-none-eabi\n$ sudo apt-get install gdb-arm-none-eabi",
"title": "Install Tool Chain"
},
{
@@ -5777,70 +5777,55 @@
},
{
"location": "/network/ble/ble_intro/",
- "text": "",
+ "text": "BLE Introduction\n\n\nApache Mynewt offers the world's first fully open-source Bluetooth Low Energy (BLE) or Bluetooth Smart stack. It is called NimBLE. \n\n\nBLE technology operates in the unlicensed industrial, scientific and medical (ISM) band at 2.4 to 2.485 GHz which is available in most countries. It uses a spread spectrum, frequency hopping, full-duplex signal. BLE FHSS employs 40 2-MHz-wide channels to ensure greater reliability over longer distances. It also features 0-dBm (1 mW) power output and a typical maximum range of 50 meters. Note that BLE is not compatible with standard Bluetooth.\n\n\n\n\nFeatures\n\n\nNimBLE complies with Bluetooth Core Specification 4.2 which introduces several new features that make it an ideal wireless technology for the Internet of Things (IoT).\n\n\n\n\nLE Privacy 1.2 for frequent changes to the device address to make it difficult to track for outsiders \nRoadmap\n\n\nLE Secure Connections featuring FIPS-compliant algori
thms. \nRoadmap\n\n\nLE Data Length Extension for higher throughput \nAvailable now\n\n\nEnables users to assign an Internet Protocol (IP) address (complaint with the IPv6 or 6LoWPAN standard) to a Bluetooth device through Internet Protocol Support Profile (IPSP) \nRoadmap\n\n\n\n\nNimBLE supports features from older specifications including,\n\n\n\n\nSupport multiple roles (master(central)/slave(peripheral), server/client) simultaneously\n\n\nSupport simultaneous advertising and scanning\n\n\nSupport being slave to multiple masters simultaneously (subject to memory and scheduling constraints)\n\n\nLow Duty Cycle Directed Advertising\n\n\nConnection parameters request procedure\n\n\nLE Ping\n\n\n32 bits UUID\n\n\nL2CAP Connection Oriented Channels\n\n\n\n\n\n\nComponents\n\n\nA Bluetooth low energy stack (NimBLE included) consists of two components with several subcomponents:\n\n\n\n\n\n\nController\n\n\n\n\nPhysical Layer\n: adaptive frequency-hopping Gaussian Frequency Shift Keyin
g (GFSK) radio using 40 RF channels (0-39), with 2 MHz spacing.\n\n\nLink Layer\n: with one of five states (Standby, Advertising, Scanning, Initiating, Connection states) active at any time\n\n\n\n\n\n\n\n\nHost\n\n\n\n\nLogical Link Control and Adaptation Protocol (L2CAP)\n: provides logical channels, named L2CAP channels, which are multiplexed over one or more logical links to provide packet segmentation and reassembly, flow control, error control, streaming, QoS etc. \n\n\nSecurity Manager (SM)\n: uses Security Manager Protocol (SMP) for pairing and transport specific key distribution for securing radio communication \n\n\nAttribute protocol (ATT)\n: allows a device (\nServer\n) to expose certain pieces of data, known as \nAttributes\n, to another device (\nClient\n)\n\n\nGeneric Attribute Profile (GATT)\n: a framework for using the ATT protocol to exchange attributes encapsulated as \nCharacteristics\n or \nServices\n \n\n\nGeneric Access Profile (GAP)\n: a base profile which al
l Bluetooth devices implement, which in the case of LE, defines the Physical Layer, Link Layer, L2CAP, Security Manager, Attribute Protocol and Generic Attribute Profile. \n\n\nHost Controller Interface (HCI)\n: the interface between the host and controller either through software API or by a hardware interface such as SPI, UART or USB.\n\n\n\n\n\n\n\n\nSubsequent chapters in this manual will go into the details of the implementation of each component, APIs available, and things to consider while designing a NimBLE app.\n\n\n\n\nExample NimBLE projects\n\n\nMynewt comes with two built-in projects that allow users to play with NimBLE, try the tutorials out with, and see how to use available services.\n\n\n\n\nbletiny\n : A simple shell application which provides a basic interface to the host-side of the BLE stack. \n\n\nbleprph\n: A basic peripheral device with no user interface. It advertises automatically on startup, and resumes advertising whenever a connection is terminated. It s
upports a maximum of one connection.",
"title": "toc"
},
{
+ "location": "/network/ble/ble_intro/#ble-introduction",
+ "text": "Apache Mynewt offers the world's first fully open-source Bluetooth Low Energy (BLE) or Bluetooth Smart stack. It is called NimBLE. BLE technology operates in the unlicensed industrial, scientific and medical (ISM) band at 2.4 to 2.485 GHz which is available in most countries. It uses a spread spectrum, frequency hopping, full-duplex signal. BLE FHSS employs 40 2-MHz-wide channels to ensure greater reliability over longer distances. It also features 0-dBm (1 mW) power output and a typical maximum range of 50 meters. Note that BLE is not compatible with standard Bluetooth.",
+ "title": "BLE Introduction"
+ },
+ {
+ "location": "/network/ble/ble_intro/#features",
+ "text": "NimBLE complies with Bluetooth Core Specification 4.2 which introduces several new features that make it an ideal wireless technology for the Internet of Things (IoT). LE Privacy 1.2 for frequent changes to the device address to make it difficult to track for outsiders Roadmap LE Secure Connections featuring FIPS-compliant algorithms. Roadmap LE Data Length Extension for higher throughput Available now Enables users to assign an Internet Protocol (IP) address (complaint with the IPv6 or 6LoWPAN standard) to a Bluetooth device through Internet Protocol Support Profile (IPSP) Roadmap NimBLE supports features from older specifications including, Support multiple roles (master(central)/slave(peripheral), server/client) simultaneously Support simultaneous advertising and scanning Support being slave to multiple masters simultaneously (subject to memory and scheduling constraints) Low Duty Cycle Directed Advertising Connection parameters request proce
dure LE Ping 32 bits UUID L2CAP Connection Oriented Channels",
+ "title": "Features"
+ },
+ {
+ "location": "/network/ble/ble_intro/#components",
+ "text": "A Bluetooth low energy stack (NimBLE included) consists of two components with several subcomponents: Controller Physical Layer : adaptive frequency-hopping Gaussian Frequency Shift Keying (GFSK) radio using 40 RF channels (0-39), with 2 MHz spacing. Link Layer : with one of five states (Standby, Advertising, Scanning, Initiating, Connection states) active at any time Host Logical Link Control and Adaptation Protocol (L2CAP) : provides logical channels, named L2CAP channels, which are multiplexed over one or more logical links to provide packet segmentation and reassembly, flow control, error control, streaming, QoS etc. Security Manager (SM) : uses Security Manager Protocol (SMP) for pairing and transport specific key distribution for securing radio communication Attribute protocol (ATT) : allows a device ( Server ) to expose certain pieces of data, known as Attributes , to another device ( Client ) Generic Attribute Profile (GATT) : a framewo
rk for using the ATT protocol to exchange attributes encapsulated as Characteristics or Services Generic Access Profile (GAP) : a base profile which all Bluetooth devices implement, which in the case of LE, defines the Physical Layer, Link Layer, L2CAP, Security Manager, Attribute Protocol and Generic Attribute Profile. Host Controller Interface (HCI) : the interface between the host and controller either through software API or by a hardware interface such as SPI, UART or USB. Subsequent chapters in this manual will go into the details of the implementation of each component, APIs available, and things to consider while designing a NimBLE app.",
+ "title": "Components"
+ },
+ {
+ "location": "/network/ble/ble_intro/#example-nimble-projects",
+ "text": "Mynewt comes with two built-in projects that allow users to play with NimBLE, try the tutorials out with, and see how to use available services. bletiny : A simple shell application which provides a basic interface to the host-side of the BLE stack. bleprph : A basic peripheral device with no user interface. It advertises automatically on startup, and resumes advertising whenever a connection is terminated. It supports a maximum of one connection.",
+ "title": "Example NimBLE projects"
+ },
+ {
"location": "/network/ble/nimble_setup/",
- "text": "Set up a NimBLE application\n\n\nThis tutorial explains how to setup an application using the Nimble stack. The end result will be a framework that you can use to create your own BLE application using the nimble stack.\n\n\nThis tutorial assumes that you have already installed a source tree and are familiar with the newt tools and concepts.\n\n\nCreate the application directory\n\n\n\n\nCreate the target\n\n\nThe first step will be to create the target that you will use to build your application. We will call this target \"ble_tgt\". Type the \nnewt target create ble_tgt\n command. You should get this:\n\n\n$ newt target create ble_tgt\nTarget targets/ble_tgt successfully created\n\n\n\n\n\nWhat this command just did was to create a directory called \nble_tgt\n in the targets directory of your project. Two files are created in that directory: pkg.yml and target.yml.\n\n\nThe target is not yet complete though! We need to set some target variables for this project
. Currently, the nimble stack has been ported to the Nordic nrf5x chipsets; specifically the nrf51 and nrf52. This application will use the nrf52 but we will also show the setup for the nrf51 in case your project uses that chip.\n\n\nHere is the command you will need to setup your target for the nrf52:\n\n\n$ newt target set ble_tgt app=apps/ble_app \\\n bsp=hw/bsp/nrf52pdk \\\n build_profile=optimized\nTarget targets/ble_tgt successfully set target.app to apps/ble_app\nTarget targets/ble_tgt successfully set target.bsp to hw/bsp/nrf52pdk\nTarget targets/ble_tgt successfully set target.build_profile to optimized\n\n\n\n\n\nHere is the command you will need to setup your target for the nrf51:\n\n\n$ newt target set ble_tgt app=apps/ble_app \\\n bsp=hw/bsp/nrf51dk \\\n build_profile=optimized\nTarget targets/ble_tgt successfully set target.app to apps/ble_
app\nTarget targets/ble_tgt successfully set target.bsp to hw/bsp/nrf51dk\nTarget targets/ble_tgt successfully set target.build_profile to optimized\n\n\n\n\n\n\n\nNimble stack initialization\n\n\nWe are now going to explain how to setup your application to initialize the nimble stack and to get the basic stack, and its required modules, initialized and up and running. Note that the code shown here is an example of what is required for nimble stack operation; it is not intended to dictate to the developer exactly how to organize/setup your code. For example, the code sample shows modification of main.c in the application /src folder. The developer has the flexibility to organize the code as they see fit so this code does not need to reside in /src/main.c nor in the main() function itself. The only possible issue is the order of some of the initializations. Where this order is important it is indicated in the tutorial.\n\n\nA note about the code samples: the main() function in each c
ode sample builds upon the previous example. However, code outside of main() shows only what we add for each step. The last code sample shows the entire main.c that we created.\n\n\nLet's start with a very basic main() function (shown below). In this main all we are doing is initializing the Mynewt OS and starting it.\n\n\n#include \nos/os.h\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}\n\n\n\n\n\nThe Nimble stack requires a number of packages/modules to be initialized prior to being initialized. We are going to add these one by one to the application and describe each.\n\n\n\n\nAdd cputime\n\n\nThe Nimble stack requires \"cputime\". This is provided by the Mynewt HAL of the\nsame name. The cputime HAL provides a high resolution timer that is used by the\nnimble stack (as the BLE specif
ication requires a fairly high resolution timer\nand has fairly tight timing requirements). The cputime HAL allows the user to\nspecify the timer resolution as different applications may require a different\nresolution. While the Nimble stack does not require a specific timer resolution\nper se, a resolution that is too large may affect performance and power\nefficiency. A suggested clock rate for HAL cputime for the nimble stack is 1\nMHz, or 1 microsecond per cputime tick. This provides enough resolution for\nmost needs while providing the Nimble stack enough resolution to implement the\nBLE specification.\n\n\nAdd the initialization of cputime to your application:\n\n\n#include \nhal/hal_cputime.h\n\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n\n \n/* Initialize OS */\n\n \nos_init\n();\n\n\n \n/* Set cputime to count at 1 usec increments */\n\n\n \nrc\n \n=\n \ncputime_init\n(\n1000000\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Start the O
S */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}\n\n\n\n\n\n\n\nCreate the system memory buffer pool\n\n\nThe Nimble stack allocates packet buffers (called mbufs) from the system memory buffer pool (msys). The system memory buffer pool and mbufs are described in the OS manual; we suggest reading that section in order to become familiar with mbufs if you are not already familiar with them. Note that the application itself (the unique application code that you are writing) does not need to use mbufs and none of the BLE host API exposed to the application developer uses them. However, the Nimble stack does require the existence of the system memory pool.\n\n\nCreating the memory pool and registering it with the system memory buffer pool can be a bit tricky the first time. However, using the template provided below it should be much easier. The header file /net/nimble/include/nimble/ble.h, which sho
uld be included in main.c, contains some MBUF macros that you will need to create the memory pool used by msys. The macro \nBLE_MBUF_PAYLOAD_SIZE\n defines the maximum amount of user payload, plus overhead, that a link layer BLE PDU can contain. The macro \nBLE_MBUF_MEMBLOCK_OVERHEAD\n is the amount of overhead required by the Nimble stack in each memory block used by the mbuf pool. The macro \nMBUF_NUM_MBUFS\n defines the number of mbufs in the mbuf pool and is defined locally. The user must determine, based on application requirements and platform memory size, how many mbufs are required. For example, if your application expects to have many simultaneous connections you may want to increase the size of the mbuf pool. In the example below, we assume you are only using a small number of active connections (2 to 3).\n\n\nA note about the size of the mbufs and \nBLE_MBUF_PAYLOAD_SIZE\n. Msys allows for multiple mbuf pools of various size. Currently, the Nimble stack requires that msys
has an mbuf pool registered that can accommodate the maximum size BLE LL PDU. Thus, we only show the creation of one mbuf pool of maximum size mbufs which gets registered to the system mbuf memory pool. We plan on modifying the Nimble stack so that smaller mbufs can be used (to conserve memory) but at this point in time you cannot modify \nBLE_MBUF_PAYLOAD_SIZE\n. Furthermore, you cannot add a mbuf pool of smaller size elements to the msys pool as the msys code might then allocate a mbuf that is too small for the nimble stack.\n\n\n/* Create a mbuf pool of BLE mbufs */\n\n\n#define MBUF_NUM_MBUFS (8)\n\n\n#define MBUF_BUF_SIZE OS_ALIGN(BLE_MBUF_PAYLOAD_SIZE, 4)\n\n\n#define MBUF_MEMBLOCK_SIZE (MBUF_BUF_SIZE + BLE_MBUF_MEMBLOCK_OVERHEAD)\n\n\n#define MBUF_MEMPOOL_SIZE OS_MEMPOOL_SIZE(MBUF_NUM_MBUFS, MBUF_MEMBLOCK_SIZE)\n\n\n\n\nstruct\n \nos_mbuf_pool\n \ng_mbuf_pool\n;\n\nstruct\n \nos_mempool\n \ng_mbuf_mempool\n;\n\nos_membuf_t\n \ng_mbuf_buffer\n[\nMBUF_MEMPOOL_SIZ
E\n];\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Set cputime to count at 1 usec increments */\n\n \nrc\n \n=\n \ncputime_init\n(\n1000000\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Create memory pool for Nimble packets and register with Msys */\n\n\n \nrc\n \n=\n \nos_mempool_init\n(\ng_mbuf_mempool\n, \nMBUF_NUM_MBUFS\n,\n\n \nMBUF_MEMBLOCK_SIZE\n, \ng_mbuf_buffer\n[\n0\n], \nmbuf_pool\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n\n \nrc\n \n=\n \nos_mbuf_pool_init\n(\ng_mbuf_pool\n, \ng_mbuf_mempool\n, \nMBUF_MEMBLOCK_SIZE\n,\n\n \nMBUF_NUM_MBUFS\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n\n \nrc\n \n=\n \nos_msys_register\n(\ng_mbuf_pool\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0
\n);\n}\n\n\n\n\n\n\n\nInitializing the device address\n\n\nThe BLE specification requires that devices have an address (called a device address). This address can be either a public device address or a random device address. The current Nimble stack implementation requires that these addresses be defined somewhere in the application; they are not defined within the Nimble stack itself. This was done so that the entire application could have access to these addresses. We expect that we will move these addresses into the Nimble stack in a future release.\n\n\nThe two variables that must be defined are named \ng_dev_addr\n (public device address) and \ng_random_addr\n (static random address). The device address must be initialized prior to initializing the Nimble stack. The random address does not have to be initialized ahead of time as it is possible to set the random address in the Nimble controller when it is running. In this example, we only initialize the device address. The comp
any OUI in this example is 0a:bb:cc; the unique portion is 11:22:33 for a device address equal to 0a:bb:cc:11:22:33. Note that we store the address in little endian order as BLE expects the OUI to be in the most significant bytes.\n\n\n/* Our global device address (public) */\n\n\nuint8_t\n \ng_dev_addr\n[\nBLE_DEV_ADDR_LEN\n];\n\n\n\n/* Our random address (static) */\n\n\nuint8_t\n \ng_random_addr\n[\nBLE_DEV_ADDR_LEN\n];\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Set cputime to count at 1 usec increments */\n\n \nrc\n \n=\n \ncputime_init\n(\n1000000\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Create memory pool for Nimble packets and register with Msys */\n\n \nrc\n \n=\n \nos_mempool_init\n(\ng_mbuf_mempool\n, \nMBUF_NUM_MBUFS\n,\n \nMBUF_MEMBLOCK_SIZE\n, \ng_mbuf_buffer\n[\n0\n], \nmbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_mbuf_pool_init\n(\
ng_mbuf_pool\n, \ng_mbuf_mempool\n, \nMBUF_MEMBLOCK_SIZE\n,\n \nMBUF_NUM_MBUFS\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_msys_register\n(\ng_mbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Initialize our device address */\n\n\n \ng_dev_addr\n[\n0\n] \n=\n \n0x33\n;\n\n \ng_dev_addr\n[\n1\n] \n=\n \n0x22\n;\n\n \ng_dev_addr\n[\n2\n] \n=\n \n0x11\n;\n\n \ng_dev_addr\n[\n3\n] \n=\n \n0xcc\n;\n\n \ng_dev_addr\n[\n4\n] \n=\n \n0xbb\n;\n\n \ng_dev_addr\n[\n5\n] \n=\n \n0x0a\n;\n\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}\n\n\n\n\n\n\n\nInitializing the statistics package\n\n\nThe Nimble stack uses the statistics package and this must be initialized prior to initializing the Nimble stack. Initializing the statistics package is quite simple; all you need to do is call the initialization fu
nction \nstats_module_init()\n.\n\n\n#include \nstats/stats.h\n\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Set cputime to count at 1 usec increments */\n\n \nrc\n \n=\n \ncputime_init\n(\n1000000\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Create memory pool for Nimble packets and register with Msys */\n\n \nrc\n \n=\n \nos_mempool_init\n(\ng_mbuf_mempool\n, \nMBUF_NUM_MBUFS\n,\n \nMBUF_MEMBLOCK_SIZE\n, \ng_mbuf_buffer\n[\n0\n], \nmbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_mbuf_pool_init\n(\ng_mbuf_pool\n, \ng_mbuf_mempool\n, \nMBUF_MEMBLOCK_SIZE\n,\n \nMBUF_NUM_MBUFS\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_msys_register\n(\ng_mbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Initialize our device address */\n\n \ng_dev_addr\n[\n0\n] \n=\n \n0x33\n;\n \ng_dev_addr\n[\n1\n] \n
=\n \n0x22\n;\n \ng_dev_addr\n[\n2\n] \n=\n \n0x11\n;\n \ng_dev_addr\n[\n3\n] \n=\n \n0xcc\n;\n \ng_dev_addr\n[\n4\n] \n=\n \n0xbb\n;\n \ng_dev_addr\n[\n5\n] \n=\n \n0x0a\n;\n\n\n \n/* Initialize the statistics package */\n\n\n \nrc\n \n=\n \nstats_module_init\n();\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}\n\n\n\n\n\n\n\nInitializing the console package\n\n\nThe console is also required by the Nimble stack. The console is currently used for log output so it needs to be initialized. For this example, we are not going to use a console receive callback. All this means is that input from the console will not be accepted by default; the developer will have to install their own handler or use one provided by another package (the shell, for example). Just like statistics, the console is initialized by calling the
console initialization function \nconsole_init()\n.\n\n\n#include \nconsole/console.h\n\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Set cputime to count at 1 usec increments */\n\n \nrc\n \n=\n \ncputime_init\n(\n1000000\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Create memory pool for Nimble packets and register with Msys */\n\n \nrc\n \n=\n \nos_mempool_init\n(\ng_mbuf_mempool\n, \nMBUF_NUM_MBUFS\n,\n \nMBUF_MEMBLOCK_SIZE\n, \ng_mbuf_buffer\n[\n0\n], \nmbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_mbuf_pool_init\n(\ng_mbuf_pool\n, \ng_mbuf_mempool\n, \nMBUF_MEMBLOCK_SIZE\n,\n \nMBUF_NUM_MBUFS\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_msys_register\n(\ng_mbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Initialize our device address */\n\n \ng_dev_addr\n[\n0\n] \n=\n \n0x33\n;\n
\ng_dev_addr\n[\n1\n] \n=\n \n0x22\n;\n \ng_dev_addr\n[\n2\n] \n=\n \n0x11\n;\n \ng_dev_addr\n[\n3\n] \n=\n \n0xcc\n;\n \ng_dev_addr\n[\n4\n] \n=\n \n0xbb\n;\n \ng_dev_addr\n[\n5\n] \n=\n \n0x0a\n;\n\n \n/* Initialize the statistics package */\n\n \nrc\n \n=\n \nstats_module_init\n();\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Init the console */\n\n\n \nrc\n \n=\n \nconsole_init\n(\nNULL\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}\n\n\n\n\n\n\n\nInitializing the Nimble controller\n\n\nThe Nimble controller is initialized via a call to \nble_ll_init()\n. This function is declared as follows:\n\n\nint\n \nble_ll_init\n(\nuint8_t\n \nll_task_prio\n, \nuint8_t\n \nnum_acl_pkts\n, \nuint16_t\n \nacl_pkt_size\n)\n\n\n\n\n\nThis function's parameters are documented below.\n\n\n\n\n\n\n\n\nParameter
\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nprio\n\n\nThe priority of the Nimble controller task. A lower number corresponds to higher priority.\n\n\n\n\n\n\nnum_acl_pkts\n\n\nThe maximum number of outstanding data packets that the controller will accept from the host.\n\n\n\n\n\n\nacl_pkt_size\n\n\nThe maximum data packet size that the controller will accept from the host.\n\n\n\n\n\n\n\n\nprio\n:\n\n\nIf you are not familiar with multitasking, preemptive operating systems we\nhighly encourage you to read the Core OS section of Mynewt OS manual. It is up\nto the application developer to decide the priority of tasks in the system.\nNote that the lower the priority number the higher the priority in the OS. For\nexample, if a task is running at priority 5 and a task at priority 3 wants to\nrun, the task at priority 5 gets preempted as the other task is a higher\nproiority.\n\n\nIn the example shown below, the LL task is configured to have the highest\npriority (priority 0). We recommend m
aking the BLE LL task the highest priority\ntask in your application as it has fairly rigorous timing requirements and\nallowing other tasks to preempt the LL task could cause undesirable behavior.\nNote that we do not force this to be the case as an application may require a\ntask to be even higher priority than the LL task. Just be warned: a task\nhigher in priority than the LL task should not perform actions that take too\nlong; even a few milliseconds could cause undesirable behavior.\n\n\nnum_acl_pkts\n and \nacl_pkt_size\n:\n\n\nThese two parameters are used to limit the amount of data the host tries to send through the controller. Nimble uses the msys facility for allocating data packets, so the product of these arguments must not be larger than the total amount of memory allocated for msys. The below example uses some values that are reasonable for most uses.\n\n\n#include \ncontroller/ble_ll.h\n\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n \nstruct\n \nb
le_hs_cfg\n \ncfg\n;\n\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Set cputime to count at 1 usec increments */\n\n \nrc\n \n=\n \ncputime_init\n(\n1000000\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Create memory pool for Nimble packets and register with Msys */\n\n \nrc\n \n=\n \nos_mempool_init\n(\ng_mbuf_mempool\n, \nMBUF_NUM_MBUFS\n,\n \nMBUF_MEMBLOCK_SIZE\n, \ng_mbuf_buffer\n[\n0\n], \nmbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_mbuf_pool_init\n(\ng_mbuf_pool\n, \ng_mbuf_mempool\n, \nMBUF_MEMBLOCK_SIZE\n,\n \nMBUF_NUM_MBUFS\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_msys_register\n(\ng_mbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Initialize our device address */\n\n \ng_dev_addr\n[\n0\n] \n=\n \n0x33\n;\n \ng_dev_addr\n[\n1\n] \n=\n \n0x22\n;\n \ng_dev_addr\n[\n2\n] \n=\n \n0x11\n;\n \ng_dev_addr\n[\n3\n] \n=\n \n0xcc\n;\
n \ng_dev_addr\n[\n4\n] \n=\n \n0xbb\n;\n \ng_dev_addr\n[\n5\n] \n=\n \n0x0a\n;\n\n \n/* Initialize the statistics package */\n\n \nrc\n \n=\n \nstats_module_init\n();\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Initialize the BLE LL */\n\n\n \nrc\n \n=\n \nble_ll_init\n(\n0\n, \n7\n, \n260\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}\n\n\n\n\n\n\n\nInitializing the Nimble host\n\n\nThe Nimble host is initialized via a call to \nble_hs_init()\n. This function is declared as follows:\n\n\nint\n \nble_hs_init\n(\nuint8_t\n \nprio\n, \nstruct\n \nble_hs_cfg\n \n*cfg\n)\n\n\n\n\n\nThe parameters are documented below.\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nprio\n\n\nThe priority of the Nimble host task. A lower number corresponds to higher priority.\n\n\n\n\n\n\ncfg\n\n\nA point
er to the desired host configuration, or \nNULL\n if you want to use the default settings.\n\n\n\n\n\n\n\n\nprio\n:\n\n\nUnlike the controller, the host does not have any strict timing requirements.\nThis number should be greater than the priority of any time-critical tasks in\nyour application (remember, bigger number = lower priority!). There are no\nrestrictions with regards to the host task's priority relative to its client\ntasks. In the below example, the host is assigned a priority of 1.\n\n\ncfg\n:\n\n\nAs mentioned above, passing a \ncfg\n value of \nNULL\n will initialize the Nimble\nhost with the default configuration. This is convenient while familiarizing\nyourself with the Nimble stack, but ultimately you will probably want to use a\ncustom configuration. For more information on configuring the host, see the\nNimble Configuration Guide (TBD).\n\n\nContinuing with our running example, we now add Nimble host initialization to the \nmain()\n function. This applicatio
n uses the default host configuration, so it specifies \nNULL\n as the second argument to \nble_hs_init()\n.\n\n\n#include \nhost/ble_hs.h\n\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n \nstruct\n \nble_hs_cfg\n \ncfg\n;\n\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Set cputime to count at 1 usec increments */\n\n \nrc\n \n=\n \ncputime_init\n(\n1000000\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Create memory pool for Nimble packets and register with Msys */\n\n \nrc\n \n=\n \nos_mempool_init\n(\ng_mbuf_mempool\n, \nMBUF_NUM_MBUFS\n,\n \nMBUF_MEMBLOCK_SIZE\n, \ng_mbuf_buffer\n[\n0\n], \nmbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_mbuf_pool_init\n(\ng_mbuf_pool\n, \ng_mbuf_mempool\n, \nMBUF_MEMBLOCK_SIZE\n,\n \nMBUF_NUM_MBUFS\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_msys_register\n(\ng_mbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\
n \n/* Initialize our device address */\n\n \ng_dev_addr\n[\n0\n] \n=\n \n0x33\n;\n \ng_dev_addr\n[\n1\n] \n=\n \n0x22\n;\n \ng_dev_addr\n[\n2\n] \n=\n \n0x11\n;\n \ng_dev_addr\n[\n3\n] \n=\n \n0xcc\n;\n \ng_dev_addr\n[\n4\n] \n=\n \n0xbb\n;\n \ng_dev_addr\n[\n5\n] \n=\n \n0x0a\n;\n\n \n/* Initialize the statistics package */\n\n \nrc\n \n=\n \nstats_module_init\n();\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Initialize the BLE LL */\n\n \nrc\n \n=\n \nble_ll_init\n(\n0\n, \n7\n, \n260\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Initialize the BLE host. */\n\n\n \nrc\n \n=\n \nble_hs_init\n(\nBLE_HS_TASK_PRI\n, \nNULL\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}\n\n\n\n\n\n\n\nBuilding the application\n\n\nNow that we have created the application and the target we can buil
d it and test it out. The command you need to run is the newt build command with the target we created (ble_tgt). The output will show the files being compiled and linked. You should see this when all is done (except for the ... of course):\n\n\nwes@~/dev/larva$ newt build ble_tgt\n...\nArchiving os.a\nCompiling cons_fmt.c\nCompiling cons_tty.c\nArchiving full.a\nLinking ble_app.elf\nApp successfully built: /Users/wes/dev/larva/bin/ble_tgt/apps/ble_app/ble_app.elf\n\n\n\n\n\nConclusion\n\n\nYou now have a fully functional BLE app (never mind the fact that it doesn't\nactually do anything yet!). With all the necessary infrastructure in place,\nyou can now start turning this into a real applicaiton. Additional tutorials\nwith focus on adding application-layer functionality to your Nimble application\nwill be coming soon. In the meantime, you might get some inspiration from\napache-mynewt-core's example Nimble apps. These apps can be found at the below locations, relative to your p
roject's base directory:\n\n\n\n\nrepos/apache-mynewt-core/apps/bleprph\n\n\nrepos/apache-mynewt-core/apps/bletiny",
+ "text": "Set up a NimBLE application\n\n\nThis tutorial explains how to setup an application using the NimBLE stack. The end result will be a framework that you can use to create your own BLE application using the nimble stack.\n\n\nThis tutorial assumes that you have already installed the newt tool and are familiar with its concepts.\n\n\nCreate the application directory\n\n\nYou start by creating a project space for your own application work using the Newt tool (\nmy_app1\n in this example) and installing all the additional apps and libraries available by adding the repo \napache-mynewt-core\n. See the tutorial on \nadding a repo\n for more on working with repos.\n\n\n$ newt new my_app1\nDownloading project skeleton from apache/incubator-mynewt-blinky...\nInstalling skeleton in my_app1...\nProject my_app1 successfully created.\n$ tree\n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u25
00 apps\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 src\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 main.c\n\u251c\u2500\u2500 project.yml\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 target.yml\n \u2514\u2500\u2500 unittest\n \u251c\u2500\u2500 pkg.yml\n \u2514\u2500\u2500 target.yml\n\n6 directories, 11 files\n\n$ cd my_app1\n$ newt install\napache-mynewt-core\n$ tree \n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 apps\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 src\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 main.c\n\u251c\u2500\u2500 project.state\n\u251c\u2500\u2
500 project.yml\n\u251c\u2500\u2500 repos\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 apache-mynewt-core\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 DISCLAIMER\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 LICENSE\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 NOTICE\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 README.md\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 RELEASE_NOTES.md\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 apps\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 bleprph\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 src\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 bleprph.h\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 gatt_svr.c\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 main.c\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 bletest\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u250
0\u2500 pkg.yml\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 src\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 main.c\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 bletiny\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 src\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 bletiny_priv.h\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 cmd.c\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 main.c\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 parse.c\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 periph.c\n\nsnip\n\n\n232 directories, 846 files\n\n\n\n\n\n\n\nIt's time to build your own app usi
ng one or more of the example apps available in the repo \napache-mynewt-core\n. \n\n\n$ ls repos/apache-mynewt-core/apps\nbleprph bletiny boot luatest test\nbletest blinky ffs2native slinky\n\n\n\n\n\n\n\nAt the very least your app must contain a \nmain.c()\n and a \npkg.yml\n file. So copy the ones from \nbletiny\n. And start enhancing it for your own custom use case!\n\n\n\n\nCreate the target\n\n\nNow you have to create the target that you will use to build your application. We will call this target \"ble_tgt\". Type the \nnewt target create ble_tgt\n command. You should get this:\n\n\n$ newt target create ble_tgt\nTarget targets/ble_tgt successfully created\n\n\n\n\n\nWhat this command just did was to create a directory called \nble_tgt\n in the targets directory of your project. Two files are created in that directory: pkg.yml and target.yml.\n\n\nThe target is not yet complete though! We need to set some target variables for this project. Currentl
y, the nimble stack has been ported to the Nordic nrf5x chipsets; specifically the nrf51 and nrf52. This application will use the nrf52 but we will also show the setup for the nrf51 in case your project uses that chip.\n\n\nHere is the command you will need to setup your target for the nrf52:\n\n\n$ newt target set ble_tgt app=apps/ble_app \\\n bsp=hw/bsp/nrf52pdk \\\n build_profile=optimized\nTarget targets/ble_tgt successfully set target.app to apps/ble_app\nTarget targets/ble_tgt successfully set target.bsp to hw/bsp/nrf52pdk\nTarget targets/ble_tgt successfully set target.build_profile to optimized\n\n\n\n\n\nHere is the command you will need to setup your target for the nrf51:\n\n\n$ newt target set ble_tgt app=apps/ble_app \\\n bsp=hw/bsp/nrf51dk \\\n build_profile=optimized\nTarget targets/ble_tgt successfully set target.app to apps/ble_app\nTarge
t targets/ble_tgt successfully set target.bsp to hw/bsp/nrf51dk\nTarget targets/ble_tgt successfully set target.build_profile to optimized\n\n\n\n\n\n\n\nNimble stack initialization\n\n\nThere are certain stack initialization steps that are required for a BLE application to be up and running. If you are running a canned example (e.g. bletiny), these steps are already done for you. When you are writing your own app, you may want to assign different initial values or initialize additional packages that you may have added to your project or written yourself. \n\n\nDetails of the initialization step requirements are covered in the section on how to \nInitialize Stack\n.\n\n\n\n\nBuilding the application\n\n\nNow that we have created the application and the target we can build it and test it out. The command you need to run is the newt build command with the target we created (ble_tgt). The output will show the files being compiled and linked. You should see this when all is done (except
for the ... of course):\n\n\nwes@~/dev/larva$ newt build ble_tgt\n...\nArchiving os.a\nCompiling cons_fmt.c\nCompiling cons_tty.c\nArchiving full.a\nLinking ble_app.elf\nApp successfully built: /Users/wes/dev/larva/bin/ble_tgt/apps/ble_app/ble_app.elf\n\n\n\n\n\nConclusion\n\n\nYou now have a fully functional BLE app (never mind the fact that it doesn't\nactually do anything yet!). With all the necessary infrastructure in place,\nyou can now start turning this into a real applicaiton. Additional tutorials\nwith focus on adding application-layer functionality to your Nimble application\nwill be coming soon. In the meantime, you might get some inspiration from\napache-mynewt-core's example Nimble apps. These apps can be found at the below locations, relative to your project's base directory:\n\n\n\n\nrepos/apache-mynewt-core/apps/bleprph\n\n\nrepos/apache-mynewt-core/apps/bletiny",
"title": "Set up application"
},
{
"location": "/network/ble/nimble_setup/#set-up-a-nimble-application",
- "text": "This tutorial explains how to setup an application using the Nimble stack. The end result will be a framework that you can use to create your own BLE application using the nimble stack. This tutorial assumes that you have already installed a source tree and are familiar with the newt tools and concepts.",
+ "text": "This tutorial explains how to setup an application using the NimBLE stack. The end result will be a framework that you can use to create your own BLE application using the nimble stack. This tutorial assumes that you have already installed the newt tool and are familiar with its concepts.",
"title": "Set up a NimBLE application"
},
{
"location": "/network/ble/nimble_setup/#create-the-application-directory",
- "text": "",
+ "text": "You start by creating a project space for your own application work using the Newt tool ( my_app1 in this example) and installing all the additional apps and libraries available by adding the repo apache-mynewt-core . See the tutorial on adding a repo for more on working with repos. $ newt new my_app1\nDownloading project skeleton from apache/incubator-mynewt-blinky...\nInstalling skeleton in my_app1...\nProject my_app1 successfully created.\n$ tree\n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 apps\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 src\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 main.c\n\u251c\u2500\u2500 project.yml\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n \u2502\u00a0\u00a0 \u
2514\u2500\u2500 target.yml\n \u2514\u2500\u2500 unittest\n \u251c\u2500\u2500 pkg.yml\n \u2514\u2500\u2500 target.yml\n\n6 directories, 11 files\n\n$ cd my_app1\n$ newt install\napache-mynewt-core\n$ tree \n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 apps\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 src\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 main.c\n\u251c\u2500\u2500 project.state\n\u251c\u2500\u2500 project.yml\n\u251c\u2500\u2500 repos\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 apache-mynewt-core\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 DISCLAIMER\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 LICENSE\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 NOTICE\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 README.md\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 RELEASE_NOTES.md\n\u2502\u00a0
\u00a0 \u251c\u2500\u2500 apps\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 bleprph\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 src\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 bleprph.h\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 gatt_svr.c\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 main.c\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 bletest\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 src\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 main.c\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 bletiny\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n\u2502\u00a0\u00a0 \u250
2\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 src\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 bletiny_priv.h\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 cmd.c\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 main.c\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 parse.c\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 periph.c snip \n\n232 directories, 846 files It's time to build your own app using one or more of the example apps available in the repo apache-mynewt-core . $ ls repos/apache-mynewt-core/apps\nbleprph bletiny boot luatest test\nbletest blinky ffs2native slinky At the very least your app must contain a main.c() and a pkg.yml file. So copy the ones from bletiny . And start enhancing it for your own custom use case!",
"title": "Create the application directory"
},
{
"location": "/network/ble/nimble_setup/#create-the-target",
- "text": "The first step will be to create the target that you will use to build your application. We will call this target \"ble_tgt\". Type the newt target create ble_tgt command. You should get this: $ newt target create ble_tgt\nTarget targets/ble_tgt successfully created What this command just did was to create a directory called ble_tgt in the targets directory of your project. Two files are created in that directory: pkg.yml and target.yml. The target is not yet complete though! We need to set some target variables for this project. Currently, the nimble stack has been ported to the Nordic nrf5x chipsets; specifically the nrf51 and nrf52. This application will use the nrf52 but we will also show the setup for the nrf51 in case your project uses that chip. Here is the command you will need to setup your target for the nrf52: $ newt target set ble_tgt app=apps/ble_app \\\n bsp=hw/bsp/nrf52pdk \\\n
build_profile=optimized\nTarget targets/ble_tgt successfully set target.app to apps/ble_app\nTarget targets/ble_tgt successfully set target.bsp to hw/bsp/nrf52pdk\nTarget targets/ble_tgt successfully set target.build_profile to optimized Here is the command you will need to setup your target for the nrf51: $ newt target set ble_tgt app=apps/ble_app \\\n bsp=hw/bsp/nrf51dk \\\n build_profile=optimized\nTarget targets/ble_tgt successfully set target.app to apps/ble_app\nTarget targets/ble_tgt successfully set target.bsp to hw/bsp/nrf51dk\nTarget targets/ble_tgt successfully set target.build_profile to optimized",
+ "text": "Now you have to create the target that you will use to build your application. We will call this target \"ble_tgt\". Type the newt target create ble_tgt command. You should get this: $ newt target create ble_tgt\nTarget targets/ble_tgt successfully created What this command just did was to create a directory called ble_tgt in the targets directory of your project. Two files are created in that directory: pkg.yml and target.yml. The target is not yet complete though! We need to set some target variables for this project. Currently, the nimble stack has been ported to the Nordic nrf5x chipsets; specifically the nrf51 and nrf52. This application will use the nrf52 but we will also show the setup for the nrf51 in case your project uses that chip. Here is the command you will need to setup your target for the nrf52: $ newt target set ble_tgt app=apps/ble_app \\\n bsp=hw/bsp/nrf52pdk \\\n build_
profile=optimized\nTarget targets/ble_tgt successfully set target.app to apps/ble_app\nTarget targets/ble_tgt successfully set target.bsp to hw/bsp/nrf52pdk\nTarget targets/ble_tgt successfully set target.build_profile to optimized Here is the command you will need to setup your target for the nrf51: $ newt target set ble_tgt app=apps/ble_app \\\n bsp=hw/bsp/nrf51dk \\\n build_profile=optimized\nTarget targets/ble_tgt successfully set target.app to apps/ble_app\nTarget targets/ble_tgt successfully set target.bsp to hw/bsp/nrf51dk\nTarget targets/ble_tgt successfully set target.build_profile to optimized",
"title": "Create the target"
},
{
"location": "/network/ble/nimble_setup/#nimble-stack-initialization",
- "text": "We are now going to explain how to setup your application to initialize the nimble stack and to get the basic stack, and its required modules, initialized and up and running. Note that the code shown here is an example of what is required for nimble stack operation; it is not intended to dictate to the developer exactly how to organize/setup your code. For example, the code sample shows modification of main.c in the application /src folder. The developer has the flexibility to organize the code as they see fit so this code does not need to reside in /src/main.c nor in the main() function itself. The only possible issue is the order of some of the initializations. Where this order is important it is indicated in the tutorial. A note about the code samples: the main() function in each code sample builds upon the previous example. However, code outside of main() shows only what we add for each step. The last code sample shows the entire main.c that we created. Le
t's start with a very basic main() function (shown below). In this main all we are doing is initializing the Mynewt OS and starting it. #include os/os.h int main ( void )\n{\n /* Initialize OS */ \n os_init ();\n\n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n} The Nimble stack requires a number of packages/modules to be initialized prior to being initialized. We are going to add these one by one to the application and describe each.",
+ "text": "There are certain stack initialization steps that are required for a BLE application to be up and running. If you are running a canned example (e.g. bletiny), these steps are already done for you. When you are writing your own app, you may want to assign different initial values or initialize additional packages that you may have added to your project or written yourself. Details of the initialization step requirements are covered in the section on how to Initialize Stack .",
"title": "Nimble stack initialization"
},
{
- "location": "/network/ble/nimble_setup/#add-cputime",
- "text": "The Nimble stack requires \"cputime\". This is provided by the Mynewt HAL of the\nsame name. The cputime HAL provides a high resolution timer that is used by the\nnimble stack (as the BLE specification requires a fairly high resolution timer\nand has fairly tight timing requirements). The cputime HAL allows the user to\nspecify the timer resolution as different applications may require a different\nresolution. While the Nimble stack does not require a specific timer resolution\nper se, a resolution that is too large may affect performance and power\nefficiency. A suggested clock rate for HAL cputime for the nimble stack is 1\nMHz, or 1 microsecond per cputime tick. This provides enough resolution for\nmost needs while providing the Nimble stack enough resolution to implement the\nBLE specification. Add the initialization of cputime to your application: #include hal/hal_cputime.h int main ( void )\n{\n int rc ;\n\n /* Initialize OS */ \n os_in
it (); /* Set cputime to count at 1 usec increments */ rc = cputime_init ( 1000000 ); assert ( rc == 0 ); \n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n}",
- "title": "Add cputime"
- },
- {
- "location": "/network/ble/nimble_setup/#create-the-system-memory-buffer-pool",
- "text": "The Nimble stack allocates packet buffers (called mbufs) from the system memory buffer pool (msys). The system memory buffer pool and mbufs are described in the OS manual; we suggest reading that section in order to become familiar with mbufs if you are not already familiar with them. Note that the application itself (the unique application code that you are writing) does not need to use mbufs and none of the BLE host API exposed to the application developer uses them. However, the Nimble stack does require the existence of the system memory pool. Creating the memory pool and registering it with the system memory buffer pool can be a bit tricky the first time. However, using the template provided below it should be much easier. The header file /net/nimble/include/nimble/ble.h, which should be included in main.c, contains some MBUF macros that you will need to create the memory pool used by msys. The macro BLE_MBUF_PAYLOAD_SIZE defines the maximum amount of us
er payload, plus overhead, that a link layer BLE PDU can contain. The macro BLE_MBUF_MEMBLOCK_OVERHEAD is the amount of overhead required by the Nimble stack in each memory block used by the mbuf pool. The macro MBUF_NUM_MBUFS defines the number of mbufs in the mbuf pool and is defined locally. The user must determine, based on application requirements and platform memory size, how many mbufs are required. For example, if your application expects to have many simultaneous connections you may want to increase the size of the mbuf pool. In the example below, we assume you are only using a small number of active connections (2 to 3). A note about the size of the mbufs and BLE_MBUF_PAYLOAD_SIZE . Msys allows for multiple mbuf pools of various size. Currently, the Nimble stack requires that msys has an mbuf pool registered that can accommodate the maximum size BLE LL PDU. Thus, we only show the creation of one mbuf pool of maximum size mbufs which gets registered to the system mbuf
memory pool. We plan on modifying the Nimble stack so that smaller mbufs can be used (to conserve memory) but at this point in time you cannot modify BLE_MBUF_PAYLOAD_SIZE . Furthermore, you cannot add a mbuf pool of smaller size elements to the msys pool as the msys code might then allocate a mbuf that is too small for the nimble stack. /* Create a mbuf pool of BLE mbufs */ #define MBUF_NUM_MBUFS (8) #define MBUF_BUF_SIZE OS_ALIGN(BLE_MBUF_PAYLOAD_SIZE, 4) #define MBUF_MEMBLOCK_SIZE (MBUF_BUF_SIZE + BLE_MBUF_MEMBLOCK_OVERHEAD) #define MBUF_MEMPOOL_SIZE OS_MEMPOOL_SIZE(MBUF_NUM_MBUFS, MBUF_MEMBLOCK_SIZE) struct os_mbuf_pool g_mbuf_pool ; struct os_mempool g_mbuf_mempool ; os_membuf_t g_mbuf_buffer [ MBUF_MEMPOOL_SIZE ]; int main ( void )\n{\n int rc ;\n\n /* Initialize OS */ \n os_init ();\n\n /* Set cputime to count at 1 usec increments */ \n rc = cputime_init ( 1000000 );\n assert ( rc == 0 ); /* Create memo
ry pool for Nimble packets and register with Msys */ rc = os_mempool_init ( g_mbuf_mempool , MBUF_NUM_MBUFS , MBUF_MEMBLOCK_SIZE , g_mbuf_buffer [ 0 ], mbuf_pool ); assert ( rc == 0 ); rc = os_mbuf_pool_init ( g_mbuf_pool , g_mbuf_mempool , MBUF_MEMBLOCK_SIZE , MBUF_NUM_MBUFS ); assert ( rc == 0 ); rc = os_msys_register ( g_mbuf_pool ); assert ( rc == 0 ); \n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n}",
- "title": "Create the system memory buffer pool"
- },
- {
- "location": "/network/ble/nimble_setup/#initializing-the-device-address",
- "text": "The BLE specification requires that devices have an address (called a device address). This address can be either a public device address or a random device address. The current Nimble stack implementation requires that these addresses be defined somewhere in the application; they are not defined within the Nimble stack itself. This was done so that the entire application could have access to these addresses. We expect that we will move these addresses into the Nimble stack in a future release. The two variables that must be defined are named g_dev_addr (public device address) and g_random_addr (static random address). The device address must be initialized prior to initializing the Nimble stack. The random address does not have to be initialized ahead of time as it is possible to set the random address in the Nimble controller when it is running. In this example, we only initialize the device address. The company OUI in this example is 0a:bb:cc; the unique
portion is 11:22:33 for a device address equal to 0a:bb:cc:11:22:33. Note that we store the address in little endian order as BLE expects the OUI to be in the most significant bytes. /* Our global device address (public) */ uint8_t g_dev_addr [ BLE_DEV_ADDR_LEN ]; /* Our random address (static) */ uint8_t g_random_addr [ BLE_DEV_ADDR_LEN ]; int main ( void )\n{\n int rc ;\n\n /* Initialize OS */ \n os_init ();\n\n /* Set cputime to count at 1 usec increments */ \n rc = cputime_init ( 1000000 );\n assert ( rc == 0 );\n\n /* Create memory pool for Nimble packets and register with Msys */ \n rc = os_mempool_init ( g_mbuf_mempool , MBUF_NUM_MBUFS ,\n MBUF_MEMBLOCK_SIZE , g_mbuf_buffer [ 0 ], mbuf_pool );\n assert ( rc == 0 );\n\n rc = os_mbuf_pool_init ( g_mbuf_pool , g_mbuf_mempool , MBUF_MEMBLOCK_SIZE ,\n MBUF_NUM_MBUFS );\n assert ( rc == 0 );\n\n rc =
os_msys_register ( g_mbuf_pool );\n assert ( rc == 0 ); /* Initialize our device address */ g_dev_addr [ 0 ] = 0x33 ; g_dev_addr [ 1 ] = 0x22 ; g_dev_addr [ 2 ] = 0x11 ; g_dev_addr [ 3 ] = 0xcc ; g_dev_addr [ 4 ] = 0xbb ; g_dev_addr [ 5 ] = 0x0a ; \n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n}",
- "title": "Initializing the device address"
- },
- {
- "location": "/network/ble/nimble_setup/#initializing-the-statistics-package",
- "text": "The Nimble stack uses the statistics package and this must be initialized prior to initializing the Nimble stack. Initializing the statistics package is quite simple; all you need to do is call the initialization function stats_module_init() . #include stats/stats.h int main ( void )\n{\n int rc ;\n\n /* Initialize OS */ \n os_init ();\n\n /* Set cputime to count at 1 usec increments */ \n rc = cputime_init ( 1000000 );\n assert ( rc == 0 );\n\n /* Create memory pool for Nimble packets and register with Msys */ \n rc = os_mempool_init ( g_mbuf_mempool , MBUF_NUM_MBUFS ,\n MBUF_MEMBLOCK_SIZE , g_mbuf_buffer [ 0 ], mbuf_pool );\n assert ( rc == 0 );\n\n rc = os_mbuf_pool_init ( g_mbuf_pool , g_mbuf_mempool , MBUF_MEMBLOCK_SIZE ,\n MBUF_NUM_MBUFS );\n assert ( rc == 0 );\n\n rc = os_msys_register ( g_mbuf_pool );\n assert ( rc == 0
);\n\n /* Initialize our device address */ \n g_dev_addr [ 0 ] = 0x33 ;\n g_dev_addr [ 1 ] = 0x22 ;\n g_dev_addr [ 2 ] = 0x11 ;\n g_dev_addr [ 3 ] = 0xcc ;\n g_dev_addr [ 4 ] = 0xbb ;\n g_dev_addr [ 5 ] = 0x0a ; /* Initialize the statistics package */ rc = stats_module_init (); assert ( rc == 0 ); \n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n}",
- "title": "Initializing the statistics package"
- },
- {
- "location": "/network/ble/nimble_setup/#initializing-the-console-package",
- "text": "The console is also required by the Nimble stack. The console is currently used for log output so it needs to be initialized. For this example, we are not going to use a console receive callback. All this means is that input from the console will not be accepted by default; the developer will have to install their own handler or use one provided by another package (the shell, for example). Just like statistics, the console is initialized by calling the console initialization function console_init() . #include console/console.h int main ( void )\n{\n int rc ;\n\n /* Initialize OS */ \n os_init ();\n\n /* Set cputime to count at 1 usec increments */ \n rc = cputime_init ( 1000000 );\n assert ( rc == 0 );\n\n /* Create memory pool for Nimble packets and register with Msys */ \n rc = os_mempool_init ( g_mbuf_mempool , MBUF_NUM_MBUFS ,\n MBUF_MEMBLOCK_SIZE , g_mbuf_buffer [ 0 ], mbuf_pool );\n ass
ert ( rc == 0 );\n\n rc = os_mbuf_pool_init ( g_mbuf_pool , g_mbuf_mempool , MBUF_MEMBLOCK_SIZE ,\n MBUF_NUM_MBUFS );\n assert ( rc == 0 );\n\n rc = os_msys_register ( g_mbuf_pool );\n assert ( rc == 0 );\n\n /* Initialize our device address */ \n g_dev_addr [ 0 ] = 0x33 ;\n g_dev_addr [ 1 ] = 0x22 ;\n g_dev_addr [ 2 ] = 0x11 ;\n g_dev_addr [ 3 ] = 0xcc ;\n g_dev_addr [ 4 ] = 0xbb ;\n g_dev_addr [ 5 ] = 0x0a ;\n\n /* Initialize the statistics package */ \n rc = stats_module_init ();\n assert ( rc == 0 ); /* Init the console */ rc = console_init ( NULL ); assert ( rc == 0 ); \n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n}",
- "title": "Initializing the console package"
- },
- {
- "location": "/network/ble/nimble_setup/#initializing-the-nimble-controller",
- "text": "The Nimble controller is initialized via a call to ble_ll_init() . This function is declared as follows: int ble_ll_init ( uint8_t ll_task_prio , uint8_t num_acl_pkts , uint16_t acl_pkt_size ) This function's parameters are documented below. Parameter Description prio The priority of the Nimble controller task. A lower number corresponds to higher priority. num_acl_pkts The maximum number of outstanding data packets that the controller will accept from the host. acl_pkt_size The maximum data packet size that the controller will accept from the host. prio : If you are not familiar with multitasking, preemptive operating systems we\nhighly encourage you to read the Core OS section of Mynewt OS manual. It is up\nto the application developer to decide the priority of tasks in the system.\nNote that the lower the priority number the higher the priority in the OS. For\nexample, if a task is running at priority 5 and a task at pri
ority 3 wants to\nrun, the task at priority 5 gets preempted as the other task is a higher\nproiority. In the example shown below, the LL task is configured to have the highest\npriority (priority 0). We recommend making the BLE LL task the highest priority\ntask in your application as it has fairly rigorous timing requirements and\nallowing other tasks to preempt the LL task could cause undesirable behavior.\nNote that we do not force this to be the case as an application may require a\ntask to be even higher priority than the LL task. Just be warned: a task\nhigher in priority than the LL task should not perform actions that take too\nlong; even a few milliseconds could cause undesirable behavior. num_acl_pkts and acl_pkt_size : These two parameters are used to limit the amount of data the host tries to send through the controller. Nimble uses the msys facility for allocating data packets, so the product of these arguments must not be larger than the total amount of memory
allocated for msys. The below example uses some values that are reasonable for most uses. #include controller/ble_ll.h int main ( void )\n{\n int rc ;\n struct ble_hs_cfg cfg ;\n\n /* Initialize OS */ \n os_init ();\n\n /* Set cputime to count at 1 usec increments */ \n rc = cputime_init ( 1000000 );\n assert ( rc == 0 );\n\n /* Create memory pool for Nimble packets and register with Msys */ \n rc = os_mempool_init ( g_mbuf_mempool , MBUF_NUM_MBUFS ,\n MBUF_MEMBLOCK_SIZE , g_mbuf_buffer [ 0 ], mbuf_pool );\n assert ( rc == 0 );\n\n rc = os_mbuf_pool_init ( g_mbuf_pool , g_mbuf_mempool , MBUF_MEMBLOCK_SIZE ,\n MBUF_NUM_MBUFS );\n assert ( rc == 0 );\n\n rc = os_msys_register ( g_mbuf_pool );\n assert ( rc == 0 );\n\n /* Initialize our device address */ \n g_dev_addr [ 0 ] = 0x33 ;\n g_dev_addr [ 1 ] = 0x22 ;\n g_dev_addr
[ 2 ] = 0x11 ;\n g_dev_addr [ 3 ] = 0xcc ;\n g_dev_addr [ 4 ] = 0xbb ;\n g_dev_addr [ 5 ] = 0x0a ;\n\n /* Initialize the statistics package */ \n rc = stats_module_init ();\n assert ( rc == 0 ); /* Initialize the BLE LL */ rc = ble_ll_init ( 0 , 7 , 260 ); assert ( rc == 0 ); \n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n}",
- "title": "Initializing the Nimble controller"
- },
- {
- "location": "/network/ble/nimble_setup/#initializing-the-nimble-host",
- "text": "The Nimble host is initialized via a call to ble_hs_init() . This function is declared as follows: int ble_hs_init ( uint8_t prio , struct ble_hs_cfg *cfg ) The parameters are documented below. Parameter Description prio The priority of the Nimble host task. A lower number corresponds to higher priority. cfg A pointer to the desired host configuration, or NULL if you want to use the default settings. prio : Unlike the controller, the host does not have any strict timing requirements.\nThis number should be greater than the priority of any time-critical tasks in\nyour application (remember, bigger number = lower priority!). There are no\nrestrictions with regards to the host task's priority relative to its client\ntasks. In the below example, the host is assigned a priority of 1. cfg : As mentioned above, passing a cfg value of NULL will initialize the Nimble\nhost with the default configuration. This is convenient whi
le familiarizing\nyourself with the Nimble stack, but ultimately you will probably want to use a\ncustom configuration. For more information on configuring the host, see the\nNimble Configuration Guide (TBD). Continuing with our running example, we now add Nimble host initialization to the main() function. This application uses the default host configuration, so it specifies NULL as the second argument to ble_hs_init() . #include host/ble_hs.h int main ( void )\n{\n int rc ;\n struct ble_hs_cfg cfg ;\n\n /* Initialize OS */ \n os_init ();\n\n /* Set cputime to count at 1 usec increments */ \n rc = cputime_init ( 1000000 );\n assert ( rc == 0 );\n\n /* Create memory pool for Nimble packets and register with Msys */ \n rc = os_mempool_init ( g_mbuf_mempool , MBUF_NUM_MBUFS ,\n MBUF_MEMBLOCK_SIZE , g_mbuf_buffer [ 0 ], mbuf_pool );\n assert ( rc == 0 );\n\n rc = os_mbuf_pool_init ( g_mbuf_
pool , g_mbuf_mempool , MBUF_MEMBLOCK_SIZE ,\n MBUF_NUM_MBUFS );\n assert ( rc == 0 );\n\n rc = os_msys_register ( g_mbuf_pool );\n assert ( rc == 0 );\n\n /* Initialize our device address */ \n g_dev_addr [ 0 ] = 0x33 ;\n g_dev_addr [ 1 ] = 0x22 ;\n g_dev_addr [ 2 ] = 0x11 ;\n g_dev_addr [ 3 ] = 0xcc ;\n g_dev_addr [ 4 ] = 0xbb ;\n g_dev_addr [ 5 ] = 0x0a ;\n\n /* Initialize the statistics package */ \n rc = stats_module_init ();\n assert ( rc == 0 );\n\n /* Initialize the BLE LL */ \n rc = ble_ll_init ( 0 , 7 , 260 );\n assert ( rc == 0 ); /* Initialize the BLE host. */ rc = ble_hs_init ( BLE_HS_TASK_PRI , NULL ); assert ( rc == 0 ); \n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n}",
- "title": "Initializing the Nimble host"
- },
- {
"location": "/network/ble/nimble_setup/#building-the-application",
"text": "Now that we have created the application and the target we can build it and test it out. The command you need to run is the newt build command with the target we created (ble_tgt). The output will show the files being compiled and linked. You should see this when all is done (except for the ... of course): wes@~/dev/larva$ newt build ble_tgt\n...\nArchiving os.a\nCompiling cons_fmt.c\nCompiling cons_tty.c\nArchiving full.a\nLinking ble_app.elf\nApp successfully built: /Users/wes/dev/larva/bin/ble_tgt/apps/ble_app/ble_app.elf",
"title": "Building the application"
@@ -5852,12 +5837,12 @@
},
{
"location": "/network/ble/ini_stack/ble_ini_intro/",
- "text": "Nimble stack initialization\n\n\nWe are now going to explain how to setup your application to initialize the nimble stack and to get the basic stack, and its required modules, initialized and up and running. Note that the code shown here is an example of what is required for nimble stack operation; it is not intended to dictate to the developer exactly how to organize/setup your code. For example, the code sample shows modification of main.c in the application /src folder. The developer has the flexibility to organize the code as they see fit so this code does not need to reside in /src/main.c nor in the main() function itself. The only possible issue is the order of some of the initializations. Where this order is important it is indicated in the tutorial.\n\n\nA note about the code samples: the main() function in each code sample builds upon the previous example. However, code outside of main() shows only what we add for each step. The last code sample shows t
he entire main.c that we created.\n\n\nLet's start with a very basic main() function (shown below). In this main all we are doing is initializing the Mynewt OS and starting it.\n\n\n#include \nos/os.h\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}\n\n\n\n\n\nThe Nimble stack requires a number of packages/modules to be initialized prior to being initialized. We are going to add these one by one to the application and describe each.",
+ "text": "Nimble stack initialization\n\n\nWe are now going to explain how to setup your application to initialize the nimble stack and to get the basic stack, and its required modules, initialized and up and running. Note that the code shown here is an example of what is required for nimble stack operation; it is not intended to dictate to the developer exactly how to organize/setup your code. For example, the code sample shows modification of main.c in the application /src folder. The developer has the flexibility to organize the code as they see fit so this code does not need to reside in /src/main.c or in the main() function itself. The only possible issue is the order of some of the initializations. Where this order is important it is indicated in the sections covering stack initialization. \n\n\nA note about the code samples: the main() function in each code sample builds upon the previous example. However, code outside of main() shows only what we add for each step
. The last code sample shows the entire main.c that we created.\n\n\nLet's start with a very basic main() function (shown below). In this main all we are doing is initializing the Mynewt OS and starting it.\n\n\n#include \nos/os.h\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}\n\n\n\n\n\nThe Nimble stack requires a number of packages/modules to be initialized prior to being started. We are going to add these one by one to the application and describe each.",
"title": "toc"
},
{
"location": "/network/ble/ini_stack/ble_ini_intro/#nimble-stack-initialization",
- "text": "We are now going to explain how to setup your application to initialize the nimble stack and to get the basic stack, and its required modules, initialized and up and running. Note that the code shown here is an example of what is required for nimble stack operation; it is not intended to dictate to the developer exactly how to organize/setup your code. For example, the code sample shows modification of main.c in the application /src folder. The developer has the flexibility to organize the code as they see fit so this code does not need to reside in /src/main.c nor in the main() function itself. The only possible issue is the order of some of the initializations. Where this order is important it is indicated in the tutorial. A note about the code samples: the main() function in each code sample builds upon the previous example. However, code outside of main() shows only what we add for each step. The last code sample shows the entire main.c that we created. Le
t's start with a very basic main() function (shown below). In this main all we are doing is initializing the Mynewt OS and starting it. #include os/os.h int main ( void )\n{\n /* Initialize OS */ \n os_init ();\n\n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n} The Nimble stack requires a number of packages/modules to be initialized prior to being initialized. We are going to add these one by one to the application and describe each.",
+ "text": "We are now going to explain how to setup your application to initialize the nimble stack and to get the basic stack, and its required modules, initialized and up and running. Note that the code shown here is an example of what is required for nimble stack operation; it is not intended to dictate to the developer exactly how to organize/setup your code. For example, the code sample shows modification of main.c in the application /src folder. The developer has the flexibility to organize the code as they see fit so this code does not need to reside in /src/main.c or in the main() function itself. The only possible issue is the order of some of the initializations. Where this order is important it is indicated in the sections covering stack initialization. A note about the code samples: the main() function in each code sample builds upon the previous example. However, code outside of main() shows only what we add for each step. The last code sample shows the enti
re main.c that we created. Let's start with a very basic main() function (shown below). In this main all we are doing is initializing the Mynewt OS and starting it. #include os/os.h int main ( void )\n{\n /* Initialize OS */ \n os_init ();\n\n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n} The Nimble stack requires a number of packages/modules to be initialized prior to being started. We are going to add these one by one to the application and describe each.",
"title": "Nimble stack initialization"
},
{