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/05/29 00:11:47 UTC
incubator-mynewt-site git commit: blehci project tutorial added
Repository: incubator-mynewt-site
Updated Branches:
refs/heads/master c3246c74c -> b55ab2bcf
blehci project tutorial added
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/b55ab2bc
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/b55ab2bc
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/b55ab2bc
Branch: refs/heads/master
Commit: b55ab2bcfd13f2702fad9589b4795e8e72bddbc4
Parents: c3246c7
Author: aditihilbert <ad...@runtime.io>
Authored: Sat May 28 17:11:37 2016 -0700
Committer: aditihilbert <ad...@runtime.io>
Committed: Sat May 28 17:11:37 2016 -0700
----------------------------------------------------------------------
docs/os/tutorials/add_repos.md | 304 ----------------
docs/os/tutorials/blehci_project.md | 191 ++++++++++
docs/os/tutorials/bletiny_project.md | 45 ++-
docs/os/tutorials/create_repo.md | 172 ---------
docs/os/tutorials/nimble_setup_copy.md | 543 ----------------------------
docs/os/tutorials/repo/add_repos.md | 304 ++++++++++++++++
docs/os/tutorials/repo/create_repo.md | 172 +++++++++
docs/os/tutorials/repo/upgrade_repo.md | 14 +
docs/os/tutorials/upgrade_repo.md | 14 -
mkdocs.yml | 14 +-
10 files changed, 730 insertions(+), 1043 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b55ab2bc/docs/os/tutorials/add_repos.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/add_repos.md b/docs/os/tutorials/add_repos.md
deleted file mode 100644
index 6c2137b..0000000
--- a/docs/os/tutorials/add_repos.md
+++ /dev/null
@@ -1,304 +0,0 @@
-## Adding Repositories to your Project
-
-### What is a Repository
-
-A repository is a version-ed Mynewt project, which is a collection of Mynewt packages organized in a specific way for redistribution.
-
-What differentiates a repository from a Mynewt project is the presence of a
-`repository.yml` file describing the repository. This will be described
-below. For a basic understanding of repositories you may read the [Newt Tool Manual](../../newt/newt_intro.md) and [How to create repos](create_repo.md).
-
-**Note:** For the remainder of this document we'll use the term repo as shorthand for a Mynewt repository.
-
-Repos are useful because they are an organized way for the community to share Mynewt packages and projects. In fact, the Mynewt-core is distributed as a repo.
-
-<br>
-
-### Why does Mynewt need additional repos?
-
-Repos add functionality not included in the Mynewt core. New repos might be created for several reasons.
-
-* **Expertise**. Individuals or organizations may have expertise that they want
-to share in the form of repos. For example a chip vendor may
-create a repo to hold the Mynewt support for their chips.
-* **Non-Core component**. Some components, although very useful to Mynewt users
-are not core to all Mynewt users. These are likely candidates to be held in
-different repos.
-* **Software licensing**. Some software have licenses that make them incompatible
-with the ASF (Apache Software Foundation) license policies. These may be
-valuable components to some Mynewt users, but cannot be contained in the `apache-Mynewt-core`.
-
-<br>
-
-### What Repos are in my Project
-
-The list of repos used by your project are contained within the
-`project.yml` file. An example can be seen by creating a new project:
-
-```no-highlight
-$ mkdir ~/dev
-$ cd ~/dev
-$ newt new myproj
-$ cd myproj
-```
-
-<br>
-
-View the `project.yml` section and you will see a line describing the repos:
-
-```no-highlight
-project.repositories:
- - apache-Mynewt-core
-```
-
-<br>
-
-By default, this newly created project uses a single repo called
-`apache-Mynewt-core`.
-
-If you wish to add additional repos, you would add
-additional lines to the `project.repositories` variable like this.
-
-``` hl_lines="3"
-project.repositories:
- - apache-Mynewt-core
- - another_repo_named_x
-```
-
-<br>
-
-### Repo Descriptors
-
-In addition to the repo name, the `project.yml` file must also contain
-a repo descriptor for each repository you include that gives `newt`
-information on obtaining the repo.
-
-In the same `myproj` above you will see the following repo descriptor.
-
-```no-highlight
-repository.apache-Mynewt-core:
- type: github
- vers: 0-latest
- user: apache
- repo: incubator-mynewt-core
-```
-
-A repo descriptor starts with `repository.<name>.`. In this example, the
-descriptor specifies the information for the `apache-Mynewt-core`.
-
-<br>
-
-The fields within the descriptor have the following definitions:
-
-* **type** -- The type of code storage the repo uses. The current version
-of `newt` only supports github. Future versions may support generic git or other
-code storage mechanisms.
-
-* **vers** -- The version of the repo to use for your project. A source
-code repository contains many versions of the source. This field is used to
-specify the one to use for this project. See the section on versions below
-for a detailed description of the format of this field.
-
-* **user** -- The username for the repo. On github, this is the name
-after `github.com` in the repo path. Consider the repository
-`https://github.com/apache/incubator-mynewt-core`. It has username `apache`.
-
-* **repo** -- The name of the repo. On github, this is the name after
-the username described above. Consider the repository
-`https://github.com/apache/incubator-mynewt-core`. It has username
-`incubator-mynewt-core`. This is a path to the source control
-and should not be confused with the name of the repo that you used in the
-`repository.<name>` declaration above. That name is contained elsewhere
-within the repo. See Below.
-
-<br>
-
-### Adding Existing Repos to my Project
-
-To add a new repo to your project, you have to complete two steps.
-
-* Edit the `project.yml` file and add a new repo descriptor. The previous
-section includes information on the field required in your repo descriptor.
-
-* Edit the `project/yml` file and add a new line to the `project.repositories`
-variable with the name of the repo you are adding.
-
-An example of a `project.yml` file with two repositories is shown below:
-
-```no-highlight
-project.name: "my_project"
-
-project.repositories:
- - apache-Mynewt-core
- - Mynewt_arduino_zero
-
-# Use github's distribution mechanism for core ASF libraries.
-# This provides mirroring automatically for us.
-#
-repository.apache-Mynewt-core:
- type: github
- vers: 0-latest
- user: apache
- repo: incubator-mynewt-core
-
-# a special repo to hold hardware specific stuff for arduino zero
-repository.Mynewt_arduino_zero:
- type: github
- vers: 0-latest
- user: runtimeinc
- repo: Mynewt_arduino_zero
-```
-
-<br>
-
-### What Version of the Repo to use
-
-Mynewt repos are version-ed artifacts. They are stored in source control
-systems like github. The repo descriptor in your `project.yml` file must
-specify the version of the repo you will accept into your project.
-
-For now, we are at the beginnings of Mynewt. For testing and evaluation
-please use `0-latest` in the `vers` field in your repo descriptor.
-
-```
- vers:0-latest
-```
-
-See [Create a Repo](create_repo) for a description of the versioning system and all the possible ways to specify a version to use.
-
-<br>
-
-### Identifying a Repo
-
-A repo contains Mynewt packages organized in a specific way and stored in one of the supported code storage methods described above. In other words, it is a Mynewt project with an additional file `repository.yml` which describes the repo for use by `newt` (and humans browsing them). It contains a mapping of version numbers to the actual github branches containing the source code.
-
-Note that the `repository.yml` file lives only in the master branch of the git
-repository. `Newt` will always fetch this file from the master branch and then
-use that to determine the actual branch required depending on the version
-specified in your `project.yml` file. Special care should be taken to ensure that this file exists only in the master branch.
-
-Here is the `repository.yml` file from the apache-Mynewt-core:
-
-```no-highlight
-repo.name: apache-mynewt-core
-repo.versions:
- "0.7.9": "Mynewt_0_8_0_b2_tag"
- "0-latest": "0.7.9"
- "0.8-latest": "0.7.9"
-```
-
-<br>
-
-It contains the following:
-
-* **repo.name** The external name that is used to include the library in
-your `project.yml` file. This is the name you in include in the `project.repositories` variable when adding this repository to your project.
-* **repo.versions** A description of what versions to give the user depending
-on the settings in their `project.yml` file.
-
-<br>
-
-### Repo Version
-
-The repo version number resolves to an actual git branch depending on the mapping specified in `repository.yml` for that repo. The version field argument in your `project.yml` file supports multiple formats for flexibility:
-
-```no-highlight
-<major_num>.<minor_num>.<revision_num>
-```
-
-or
-
-```no-highlight
-<major_num>.<minor_num>-<stability string>
-```
-
-or
-
-```no-highlight
-<major_num>-<stability string>
-```
-
-<br>
-
-The stability string can be one of 3 pre-defined stability values.
-
-1. stable -- A stable release version of the repository
-2. dev -- A development version from the repository
-3. latest -- The latest from the repository
-
-In your `project.yml` file you can specify different combinations of
-the version number and stability value. For example:
-
-* `0-latest` -- The latest version with major number 0
-* `1.2-stable` -- The latest stable version with major and minor number 1.2
-* `1.2-dev` -- The development version from 1.2
-* `1.1.1` -- a specific version 1.1.1
-
-You cannot specify a stability string with a fully numbered version, e.g.
-
-```no-highlight
-1.2.8-stable
-```
-
-<br>
-
-### Repo Versions Available
-
-A `repository.yml` file contains information to match a version request
-into a git branch to fetch for your project.
-
-It's up to the repository maintainer to map these to branches of the
-repository. For example, let's say in a fictitious repository the following are
-defined.
-
-```no-highlight
-repo.versions:
- "0.8.0": "xxx_branch_0_8_0"
- "1.0.0": "xxx_branch_1_0_0"
- "1.0.2": "xxx_branch_1_0_2"
- "1.1.1": "xxx_branch_1_1_0"
- "1.1.2": "xxx_branch_1_1_2"
- "1.2.0": "xxx_branch_1_2_0"
- "1.2.1": "xxx_branch_1_2_1"
- "1.2-dev": "1.2.1"
- "1-dev": "1.2-dev"
- "1.2-stable": "1.2.0"
- "0-latest": "0.8.0"
- "1-latest": "1-dev"
- ....
-```
-
-When the `project.yml` file asks for `1.2-stable` it is resolved to version
-`1.2.0` (perhaps `1.2.1` is not stable yet), which in turn resolves to a specific
-branch `xxx_branch_1_2_0`. This is the branch that `newt` fetches into
-your project.
-
-**Note:** Make sure a repo version exists in the `repository.yml` file of a repo you wish to add. Otherwise Newt will not be able to resolve the version and will fail to fetch the repo into your project.
-
-<br>
-
-### How to find out what Repos are available for Mynewt components
-
-Currently, there is no `newt` command to locate/search Mynewt package
-repositories. However, since the `newt` tool supports only github,
-searching github by keyword is a satisfactory option until a search
-tool is created.
-
-When searching github, recall that a Mynewt repository must
-have a `repository.yml` file in its root directory. If you don't see
-that file, it's not a Mynewt repository and can't be included in your
-project via the newt tool.
-
-Once you find a repository, the github URL and `repository.yml` file
-should give you all the information to add it to your `project.yml` file.
-
-<br>
-
-
-
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b55ab2bc/docs/os/tutorials/blehci_project.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/blehci_project.md b/docs/os/tutorials/blehci_project.md
new file mode 100644
index 0000000..a8ad341
--- /dev/null
+++ b/docs/os/tutorials/blehci_project.md
@@ -0,0 +1,191 @@
+## Use HCI access to NimBLE controller
+
+<br>
+
+This tutorial explains how to use the example application `blehci` included in the NimBLE stack to talk to the Mynewt NimBLE controller via the Host Controller Interface. You may build the Mynewt image using a laptop running any OS of your choice - Mac, Linux, or Windows.
+
+The host used in this specific example is the BlueZ Bluetooth stack. Since BlueZ is a Bluetooth stack for Linux kernel-based family of operating system, the tutorial expects a computer running Linux OS and with BlueZ installed to talk to the board with the Mynewt image.
+
+<br>
+
+### Pre-Requisites
+
+* Ensure you have installed [newt](../../newt/install/newt_mac.md) and that the
+newt command is in your system path.
+* You must have Internet connectivity to fetch remote Mynewt components.
+* If you are not using the Docker container for newt and other tools, you must [install the compiler tools](../get_started/native_tools.md) to
+support native compiling to build the project this tutorial creates.
+* You have a board with BLE radio that is supported by Mynewt. We will use an nRF52 Dev board in this tutorial.
+* USB TTL Serial Cable that supports hardware flow control such as ones found at [http://www.ftdichip.com/Products/Cables/USBTTLSerial.htm](http://www.ftdichip.com/Products/Cables/USBTTLSerial.htm) to establish a serial USB connection between the board and the laptop.
+* You have installed a BLE host such as BlueZ on a Linux machine to talk to the nrf52 board running Mynewt. Use `sudo apt-get install bluez` to install it on your Linux machine.
+
+<br>
+
+### Create a project
+
+Use the Newt tool to create a new project directory containing a skeletal Mynewt framework. Change into the newly created directory. Make sure the downloaded version is 0.9.0 or later.
+
+```
+$ newt new blehciproj
+Downloading project skeleton from apache/incubator-mynewt-blinky...
+Installing skeleton in blehciproj ...
+Project blehciproj successfully created.
+$ cd mblehciproj
+
+$ newt install -v
+apache-mynewt-core
+Downloading repository description for apache-mynewt-core... success!
+...
+apache-mynewt-core successfully installed version 0.9.0-none
+```
+
+<br>
+
+### Create targets
+
+You will create two targets - one for the bootloader, the other for the application. Then you will add the definitions for them. Note that you are using the example app `blehci` for the application target. Set the bsp correctly (nrf52pdk or nrf52dk depending on whether the board is the preview kit or the dev kit, respectively).
+
+```
+$ newt target create nrf52_boot
+$ newt target set nrf52_boot app=@apache-mynewt-core/apps/boot
+$ newt target set nrf52_boot bsp=@apache-mynewt-core/hw/bsp/nrf52dk
+$ newt target set nrf52_boot build_profile=optimized
+```
+```
+$ newt target create myble2
+$ newt target set myble2 bsp=@apache-mynewt-core/hw/bsp/nrf52dk
+$ newt target set myble2 app=@apache-mynewt-core/apps/blehci
+$ newt target set myble2 build_profile=optimized
+```
+
+<br>
+
+Check that the targets are defined correctly.
+
+
+```
+$ newt target show
+ targets/my_blinky_sim
+ app=apps/blinky
+ bsp=@apache-mynewt-core/hw/bsp/native
+ build_profile=debug
+ targets/myble2
+ app=@apache-mynewt-core/apps/blehci
+ bsp=@apache-mynewt-core/hw/bsp/nrf52dk
+ build_profile=optimized
+ targets/nrf52_boot
+ app=@apache-mynewt-core/apps/boot
+ bsp=@apache-mynewt-core/hw/bsp/nrf52dk
+ build_profile=optimized
+```
+
+<br>
+
+### Build targets
+
+Then build the two targets.
+
+```
+$ newt build nrf52_boot
+<snip>
+App successfully built: ./bin/nrf52_boot/apps/boot/boot.elf
+$ newt build myble2
+Compiling hci_common.c
+Compiling util.c
+Archiving nimble.a
+Compiling os.c
+<snip>
+```
+
+<br>
+
+### Create the app image
+
+Generate a signed application image for the `myble2` target. The version number is arbitrary.
+
+```
+$ newt create-image myble2 1.0.0
+App image succesfully generated: ./bin/makerbeacon/apps/bletiny/bletiny.img
+Build manifest: ./bin/makerbeacon/apps/bletiny/manifest.json
+```
+
+<br>
+
+### Load the image
+
+Make sure the USB connector is in place and the power LED on the board is lit. Use the Power ON/OFF switch to reset the board after loading the image.
+
+```
+$ newt -v load myble
+```
+
+<br>
+
+### Establish serial connection
+
+Attach a serial port to your board by connecting the USB TTL Serial Cable. This should create /dev/ttyUSB0 (or similar) on your machine.
+
+**Note** Certain Linux OS versions have been observed to detect the nrf52 board as a mass storage device and the console access doesn\u2019t work properly. In that case try powering the nrf52 board from your monitor or something other than your Linux computer/laptop when you set up the serial port for HCI communication.
+
+<br>
+
+### Open Bluetooth monitor btmon
+
+`btmon` is a BlueZ test tool to display all HCI commands and events in a human readable format. Start the btmon tool in a terminal window.
+
+```
+$ sudo btmon
+[sudo] password for admin:
+Bluetooth monitor ver 5.37
+```
+
+<br>
+
+### Attach the blehci device to BlueZ
+
+In a different terminal, attach the blehci device to the BlueZ daemon (substitute the correct /dev filename for ttyUSB0).
+
+```
+$ sudo btattach -B /dev/ttyUSB0 -S 115200
+Attaching BR/EDR controller to /dev/ttyUSB0
+Switched line discipline from 0 to 15
+Device index 1 attached
+```
+
+<br>
+
+### Start btmgmt to send commands
+
+In a third terminal, start btmgmt. This tool allows you to send commands to the blehci controller. Use the index number that shows up when you `btattach` in the previous step.
+
+```
+$ sudo btmgmt --index 1
+[sudo] password for admin:
+```
+
+Set your device address (you can substitute any static random address here).
+
+```
+[hci1]# static-addr cc:11:11:11:11:11
+Static address successfully set
+```
+
+Initialize the controller.
+
+```
+[hci1]# power on
+hci1 Set Powered complete, settings: powered le static-addr
+```
+
+Begin scanning.
+
+```
+[hci1]# find -l
+Discovery started
+hci1 type 6 discovering on
+hci1 dev_found: 58:EF:77:C8:8D:17 type LE Random rssi -78 flags 0x0000
+AD flags 0x06
+eir_len 23
+<snip>
+```
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b55ab2bc/docs/os/tutorials/bletiny_project.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/bletiny_project.md b/docs/os/tutorials/bletiny_project.md
index 40d9ecf..98ea84d 100644
--- a/docs/os/tutorials/bletiny_project.md
+++ b/docs/os/tutorials/bletiny_project.md
@@ -38,22 +38,27 @@ apache-mynewt-core successfully installed version 0.7.9-none
<br>
-### Create a target
+### Create targets
+
+You will create two targets - one for the bootloader, the other for the application.
```
$ newt target create myble
Target targets/myble successfully created
+$ newt target create nrf52_boot
+Target targets/myble successfully created
$ newt target show
targets/my_blinky_sim
app=apps/blinky
bsp=@apache-mynewt-core/hw/bsp/native
build_profile=debug
targets/myble
+targets/nrf52_boot
```
<br>
-Define the target further. Note that you are using the example app `bletiny`.
+Define the targets further. Note that you are using the example app `bletiny` for the application target. Set the bsp correctly (nrf52pdk or nrf52dk depending on whether the board is the preview kit or the dev kit, respectively).
```
$ newt target set myble bsp=@apache-mynewt-core/hw/bsp/nrf52pdk
@@ -64,6 +69,19 @@ $ newt target set myble build_profile=optimized
Target targets/myble successfully set target.build_profile to optimized
$ newt target set myble cflags=-DSTATS_NAME_ENABLE
Target targets/myble successfully set pkg.cflags to DSTATS_NAME_ENABLE
+```
+
+Use the same `newt target set` command to set the following definition for the bootloader target.
+
+```
+targets/nrf52_boot
+ app=@apache-mynewt-core/apps/boot
+ bsp=@apache-mynewt-core/hw/bsp/nrf52pdk
+ build_profile=optimized
+```
+You should have the following targets by the end of this step.
+
+```
$ newt target show
targets/my_blinky_sim
app=apps/blinky
@@ -74,13 +92,20 @@ targets/myble
bsp=@apache-mynewt-core/hw/bsp/nrf52pdk
build_profile=optimized
cflags=-DSTATS_NAME_ENABLE
+targets/nrf52_boot
+ app=@apache-mynewt-core/apps/boot
+ bsp=@apache-mynewt-core/hw/bsp/nrf52pdk
+ build_profile=optimized
```
-<br>
+### Build targets
-Then build the target.
+Then build the two targets.
```
+$ newt build nrf52_boot
+<snip>
+App successfully built: ./bin/nrf52_boot/apps/boot/boot.elf
$ newt build myble
Compiling hci_common.c
Compiling util.c
@@ -91,6 +116,18 @@ Compiling os.c
<br>
+### Create the app image
+
+Generate a signed application image for the `myble` target. The version number is arbitrary.
+
+```
+$ newt create-image myble 1.0.0
+App image succesfully generated: ./bin/makerbeacon/apps/bletiny/bletiny.img
+Build manifest: ./bin/makerbeacon/apps/bletiny/manifest.json
+```
+
+<br>
+
### Load the image
Make sure the USB connector is in place and the power LED on the board is lit. Use the Power ON/OFF switch to reset the board after loading the image.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b55ab2bc/docs/os/tutorials/create_repo.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/create_repo.md b/docs/os/tutorials/create_repo.md
deleted file mode 100644
index 1e1927e..0000000
--- a/docs/os/tutorials/create_repo.md
+++ /dev/null
@@ -1,172 +0,0 @@
-## Create a Repo out of a Project
-
-In order to create a repository out of a project, all you need to do is create a `repository.yml` file, and check it into the master branch of your project.
-
-**NOTE:** Currently only github source control service is supported by our package management system, but support for plain git will be added soon.
-
-The repository.yml defines all versions of the repository and the corresponding source control tags that these versions correspond to. As an example, if the repository.yml file has the following content, it means there is one version of the apache-mynewt-core operating system available, which is `0.0.0` (implying we haven't released yet!). Such a version number corresponds to the "develop" branch in this repository. `0-latest` would also resolved to this same `0.0.0` version. The next section explains the versioning system a bit more.
-
-```
-$ more repository.yml
-repo.name: apache-mynewt-core
-repo.versions:
- "0.0.0": "develop"
- "0-latest": "0.0.0"
-```
-
-<br>
-
-### Where should the repository.yml file be?
-
-The `repository.yml` file lives only in the master branch of the git
-repository. `Newt` will always fetch this file from the master branch and then
-use that to resolve the actual branch required depending on the version
-specified in the project. **Special care should be taken to ensure that this
-file exists only in the master branch.**
-
-Here is the `repository.yml` file from a certain snapshot of apache-Mynewt-core:
-
-```
-repo.name: apache-mynewt-core
-repo.versions:
- "0.7.9": "Mynewt_0_8_0_b2_tag"
- "0-latest": "0.7.9"
- "0.8-latest": "0.7.9"
-```
-
-<br>
-
-It contains the following:
-
-* **repo.name** The external name that is used to include the library in
-your `project.yml` file. This is the name you in include in the `project.repositories` variable when adding this repository to your project.
-* **repo.versions** A description of what versions to give the user depending
-on the settings in their `project.yml` file. See below for a thorough description
-on versioning. Its a flexible mapping between version numbers and git branches.
-
-<br>
-
-### Repo Version Specification
-
-The version field argument for a repo has the following format:
-
-```no-highlight
-<major_num>.<minor_num>.<revision_num>
-```
-
-or
-
-```no-highlight
-<major_num>.<minor_num>-<stability string>
-```
-
-or
-
-```no-highlight
-<major_num>-<stability string>
-```
-
-<br>
-
-The stability string can be one of 3 pre-defined stability values.
-
-1. stable -- A stable release version of the repository
-2. dev -- A development version from the repository
-3. latest -- The latest from the repository
-
-In your `project.yml` file you can specify different combinations of
-the version number and stability value. For example:
-
-* `0-latest` -- The latest version with major number 0
-* `1.2-stable` -- The latest stable version with major and minor number 1.2
-* `1.2-dev` -- The development version from 1.2
-* `1.1.1` -- a specific version 1.1.1
-
-You **cannot** specify a stability string with a fully numbered version, e.g.
-
-```no-highlight
-1.2.8-stable
-```
-
-<br>
-
-### Repo Version Resolution
-
-A `repository.yml` file contains information to match this version request
-into a git branch to fetch for your project.
-
-It's up to you as the repository maintainer to map these to actual github branches of the repository. For example, let's say in a fictitious repository the following are defined.
-
-```no-highlight
-repo.versions:
- "0.8.0": "xxx_branch_0_8_0"
- "1.0.0": "xxx_branch_1_0_0"
- "1.0.2": "xxx_branch_1_0_2"
- "1.1.1": "xxx_branch_1_1_0"
- "1.1.2": "xxx_branch_1_1_2"
- "1.2.0": "xxx_branch_1_2_0"
- "1.2.1": "xxx_branch_1_2_1"
- "1.2-dev": "1.2.1"
- "1-dev": "1.2-dev"
- "1.2-stable": "1.2.0"
- "0-latest": "0.8.0"
- "1-latest": "1-dev"
- ....
-```
-
-When the `project.yml` file asks for `1.2-stable` it will be resolved to version
-`1.2.0` which in turn will resolve to a specific branch `xxx_branch_1_2_0`. This is the branch that `newt` will fetch into the project with that `project.yml` file.
-
-<br>
-
-### Dependencies on other repos
-
-Repositories can also have dependencies on other repositories. These
-dependencies should be listed out on a per-tag basis. So, for example,
-if apache-mynewt-core were to depend on sterlys-little-repo, you might
-have the following directives in the repository.yml:
-
-```
-develop.repositories:
- sterlys-little-repo:
- type: github
- vers: 0.8-latest
- user: sterlinghughes
- repo: sterlys-little-repo
-```
-
-<br>
-
-This would tell Newt that for anything that resolves to the develop
-branch, this repository requires the sterlys-little-repo repository.
-
-Dependencies are resolved circularly by the newt tool, and every dependent repository is placed as a sibling in the repos directory. Currently, if two repositories have the same name, they will conflict and bad things will happen.
-
-When a repository is installed to the repos/ directory, the current
-version of that repository is written to the "project.state" file. The
-project state file contains the currently installed version of any given
-repository. This way, the current set of repositories can be recreated
-from the project.state file reliably, whereas the project.yml file can
-have higher level directives (i.e. include 0.8-stable.)
-
-
-### Resolving dependencies
-
-At the moment, all dependencies must match, otherwise newt will provide
-an error. As an example, if you have a set of dependencies such that:
-
-```
-apache-mynewt-core depends on sterlys-little-repo 0.6-stable
-apache-mynewt-core depends on sterlys-big-repo 0.5.1
-sterlys-big-repo-0.5.1 depends on sterlys-little-repo 0.6.2
-```
-
-<br>
-
-where 0.6-stable is 0.6.3, the newt tool will try and resolve the dependency to
-sterlys-little-repo. It will notice that there are two conflicting
-versions of the same repository, and not perform installation.
-
-In the future Newt will be smarter about loading in all dependencies,
-and then looking to satisfy those dependencies to the best match of all
-potential options.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b55ab2bc/docs/os/tutorials/nimble_setup_copy.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/nimble_setup_copy.md b/docs/os/tutorials/nimble_setup_copy.md
deleted file mode 100644
index f1bce25..0000000
--- a/docs/os/tutorials/nimble_setup_copy.md
+++ /dev/null
@@ -1,543 +0,0 @@
-## Nimble stack setup for BLE applications
-
-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.
-
-
-## Table of Contents
-
-[TOC]
-
-### Creating the application directory
-<This needs to be added. This should talk about how you create the pkg.yml file in the apps directory that the user will create. Also, discuss other application dir stuff>
-
-### Creating the target
-
-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:
-
-```no-highlight
-$ newt target create ble_tgt
-Target 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:
-
-```no-highlight
-$ newt target set ble_tgt app=apps/ble_app \
- bsp=hw/bsp/nrf52pdk \
- build_profile=optimized
-Target targets/ble_tgt successfully set target.app to apps/ble_app
-Target targets/ble_tgt successfully set target.bsp to hw/bsp/nrf52pdk
-Target targets/ble_tgt successfully set target.build_profile to optimized
-```
-
-Here is the command you will need to setup your target for the nrf51:
-
-```no-highlight
-$ newt target set ble_tgt app=apps/ble_app \
- bsp=hw/bsp/nrf51dk \
- build_profile=optimized
-Target targets/ble_tgt successfully set target.app to apps/ble_app
-Target targets/ble_tgt successfully set target.bsp to hw/bsp/nrf51dk
-Target targets/ble_tgt successfully set target.build_profile to optimized
-```
-
-<br>
-
-
-### Nimble stack initialization
-
-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.
-
-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.
-
-```c
-#include "os/os.h"
-
-int
-main(void)
-{
- /* Initialize OS */
- os_init();
-
- /* Start the OS */
- os_start();
-
- /* os start should never return. If it does, this should be an error */
- assert(0);
-}
-```
-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.
-
-<br>
-
-#### Add cputime
-
-The Nimble stack requires "cputime". This is provided by the Mynewt HAL of the
-same name. The cputime HAL provides a high resolution timer that is used by the
-nimble stack (as the BLE specification requires a fairly high resolution timer
-and has fairly tight timing requirements). The cputime HAL allows the user to
-specify the timer resolution as different applications may require a different
-resolution. While the Nimble stack does not require a specific timer resolution
-per se, a resolution that is too large may affect performance and power
-efficiency. A suggested clock rate for HAL cputime for the nimble stack is 1
-MHz, or 1 microsecond per cputime tick. This provides enough resolution for
-most needs while providing the Nimble stack enough resolution to implement the
-BLE specification.
-
-Add the initialization of cputime to your application:
-
-```c hl_lines="1 11 12 13"
-#include "hal/hal_cputime.h"
-
-int
-main(void)
-{
- int rc;
-
- /* Initialize OS */
- os_init();
-
- /* Set cputime to count at 1 usec increments */
- rc = cputime_init(1000000);
- assert(rc == 0);
-
- /* Start the OS */
- os_start();
-
- /* os start should never return. If it does, this should be an error */
- assert(0);
-}
-```
-
-<br>
-
-#### Create the system memory buffer pool
-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 user 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.
-
-```c hl_lines="1 2 3 4 5 6 7 8 9 23 24 25 26 27 28 29 30 31 32 33"
-/* 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)
-{
- int rc;
-
- /* Initialize OS */
- os_init();
-
- /* Set cputime to count at 1 usec increments */
- rc = cputime_init(1000000);
- assert(rc == 0);
-
- /* Create memory 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);
-
- /* Start the OS */
- os_start();
-
- /* os start should never return. If it does, this should be an error */
- assert(0);
-}
-```
-
-<br>
-
-#### Initializing the device address
-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.
-
-```c hl_lines="1 2 3 4 5 31 32 33 34 35 36 37"
-/* 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)
-{
- int rc;
-
- /* Initialize OS */
- os_init();
-
- /* Set cputime to count at 1 usec increments */
- rc = cputime_init(1000000);
- assert(rc == 0);
-
- /* Create memory 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);
-
- /* 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;
-
- /* Start the OS */
- os_start();
-
- /* os start should never return. If it does, this should be an error */
- assert(0);
-}
-```
-
-<br>
-
-#### Initializing the statistics package
-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()`.
-
-```c hl_lines="1 35 36 37"
-#include "stats/stats.h"
-
-int
-main(void)
-{
- int rc;
-
- /* Initialize OS */
- os_init();
-
- /* Set cputime to count at 1 usec increments */
- rc = cputime_init(1000000);
- assert(rc == 0);
-
- /* Create memory 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);
-
- /* 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;
-
- /* Initialize the statistics package */
- rc = stats_module_init();
- assert(rc == 0);
-
- /* Start the OS */
- os_start();
-
- /* os start should never return. If it does, this should be an error */
- assert(0);
-}
-```
-
-<br>
-
-#### Initializing the console package
-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()`.
-
-```c hl_lines="1 39 40 41"
-#include "console/console.h"
-
-int
-main(void)
-{
- int rc;
-
- /* Initialize OS */
- os_init();
-
- /* Set cputime to count at 1 usec increments */
- rc = cputime_init(1000000);
- assert(rc == 0);
-
- /* Create memory 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);
-
- /* 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;
-
- /* Initialize the statistics package */
- rc = stats_module_init();
- assert(rc == 0);
-
- /* Init the console */
- rc = console_init(NULL);
- assert(rc == 0);
-
- /* Start the OS */
- os_start();
-
- /* os start should never return. If it does, this should be an error */
- assert(0);
-}
-```
-
-<br>
-
-#### Initializing the Nimble controller
-The Nimble controller is initialized via a call to `ble_ll_init()`. This function is declared as follows:
-
-```c
-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
-highly encourage you to read the Core OS section of Mynewt OS manual. It is up
-to the application developer to decide the priority of tasks in the system.
-Note that the lower the priority number the higher the priority in the OS. For
-example, if a task is running at priority 5 and a task at priority 3 wants to
-run, the task at priority 5 gets preempted as the other task is a higher
-proiority.
-
-In the example shown below, the LL task is configured to have the highest
-priority (priority 0). We recommend making the BLE LL task the highest priority
-task in your application as it has fairly rigorous timing requirements and
-allowing other tasks to preempt the LL task could cause undesirable behavior.
-Note that we do not force this to be the case as an application may require a
-task to be even higher priority than the LL task. Just be warned: a task
-higher in priority than the LL task should not perform actions that take too
-long; 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.
-
-```c hl_lines="1 40 41 42"
-#include "controller/ble_ll.h"
-
-int
-main(void)
-{
- int rc;
- struct ble_hs_cfg cfg;
-
- /* Initialize OS */
- os_init();
-
- /* Set cputime to count at 1 usec increments */
- rc = cputime_init(1000000);
- assert(rc == 0);
-
- /* Create memory 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);
-
- /* 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;
-
- /* Initialize the statistics package */
- rc = stats_module_init();
- assert(rc == 0);
-
- /* Initialize the BLE LL */
- rc = ble_ll_init(0, 7, 260);
- assert(rc == 0);
-
- /* Start the OS */
- os_start();
-
- /* os start should never return. If it does, this should be an error */
- assert(0);
-}
-```
-<br>
-
-##### Initializing the Nimble host
-
-The Nimble host is initialized via a call to `ble_hs_init()`. This function is declared as follows:
-
-```c
-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.
-This number should be greater than the priority of any time-critical tasks in
-your application (remember, bigger number = lower priority!). There are no
-restrictions with regards to the host task's priority relative to its client
-tasks. 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
-host with the default configuration. This is convenient while familiarizing
-yourself with the Nimble stack, but ultimately you will probably want to use a
-custom configuration. For more information on configuring the host, see the
-Nimble 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()`.
-
-```c hl_lines="1 44 45 46"
-#include "host/ble_hs.h"
-
-int
-main(void)
-{
- int rc;
- struct ble_hs_cfg cfg;
-
- /* Initialize OS */
- os_init();
-
- /* Set cputime to count at 1 usec increments */
- rc = cputime_init(1000000);
- assert(rc == 0);
-
- /* Create memory 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);
-
- /* 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;
-
- /* Initialize the statistics package */
- rc = stats_module_init();
- assert(rc == 0);
-
- /* Initialize the BLE LL */
- rc = ble_ll_init(0, 7, 260);
- assert(rc == 0);
-
- /* Initialize the BLE host. */
- rc = ble_hs_init(BLE_HS_TASK_PRI, NULL);
- assert(rc == 0);
-
- /* Start the OS */
- os_start();
-
- /* os start should never return. If it does, this should be an error */
- assert(0);
-}
-```
-
-<br>
-
-### Building the application
-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):
-
-```no-highlight
-wes@~/dev/larva$ newt build ble_tgt
-...
-Archiving os.a
-Compiling cons_fmt.c
-Compiling cons_tty.c
-Archiving full.a
-Linking ble_app.elf
-App successfully built: /Users/wes/dev/larva/bin/ble_tgt/apps/ble_app/ble_app.elf
-```
-
-### Conclusion
-
-You now have a fully functional BLE app (never mind the fact that it doesn't
-actually do anything yet!). With all the necessary infrastructure in place,
-you can now start turning this into a real application. Additional tutorials
-with focus on adding application-layer functionality to your Nimble application
-will be coming soon. In the meantime, you might get some inspiration from
-apache-mynewt-core's example Nimble apps. These apps can be found at the below locations, relative to your project's base directory:
-
-* _repos/apache-mynewt-core/apps/bleprph_
-* _repos/apache-mynewt-core/apps/bletiny_
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b55ab2bc/docs/os/tutorials/repo/add_repos.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/repo/add_repos.md b/docs/os/tutorials/repo/add_repos.md
new file mode 100644
index 0000000..6c2137b
--- /dev/null
+++ b/docs/os/tutorials/repo/add_repos.md
@@ -0,0 +1,304 @@
+## Adding Repositories to your Project
+
+### What is a Repository
+
+A repository is a version-ed Mynewt project, which is a collection of Mynewt packages organized in a specific way for redistribution.
+
+What differentiates a repository from a Mynewt project is the presence of a
+`repository.yml` file describing the repository. This will be described
+below. For a basic understanding of repositories you may read the [Newt Tool Manual](../../newt/newt_intro.md) and [How to create repos](create_repo.md).
+
+**Note:** For the remainder of this document we'll use the term repo as shorthand for a Mynewt repository.
+
+Repos are useful because they are an organized way for the community to share Mynewt packages and projects. In fact, the Mynewt-core is distributed as a repo.
+
+<br>
+
+### Why does Mynewt need additional repos?
+
+Repos add functionality not included in the Mynewt core. New repos might be created for several reasons.
+
+* **Expertise**. Individuals or organizations may have expertise that they want
+to share in the form of repos. For example a chip vendor may
+create a repo to hold the Mynewt support for their chips.
+* **Non-Core component**. Some components, although very useful to Mynewt users
+are not core to all Mynewt users. These are likely candidates to be held in
+different repos.
+* **Software licensing**. Some software have licenses that make them incompatible
+with the ASF (Apache Software Foundation) license policies. These may be
+valuable components to some Mynewt users, but cannot be contained in the `apache-Mynewt-core`.
+
+<br>
+
+### What Repos are in my Project
+
+The list of repos used by your project are contained within the
+`project.yml` file. An example can be seen by creating a new project:
+
+```no-highlight
+$ mkdir ~/dev
+$ cd ~/dev
+$ newt new myproj
+$ cd myproj
+```
+
+<br>
+
+View the `project.yml` section and you will see a line describing the repos:
+
+```no-highlight
+project.repositories:
+ - apache-Mynewt-core
+```
+
+<br>
+
+By default, this newly created project uses a single repo called
+`apache-Mynewt-core`.
+
+If you wish to add additional repos, you would add
+additional lines to the `project.repositories` variable like this.
+
+``` hl_lines="3"
+project.repositories:
+ - apache-Mynewt-core
+ - another_repo_named_x
+```
+
+<br>
+
+### Repo Descriptors
+
+In addition to the repo name, the `project.yml` file must also contain
+a repo descriptor for each repository you include that gives `newt`
+information on obtaining the repo.
+
+In the same `myproj` above you will see the following repo descriptor.
+
+```no-highlight
+repository.apache-Mynewt-core:
+ type: github
+ vers: 0-latest
+ user: apache
+ repo: incubator-mynewt-core
+```
+
+A repo descriptor starts with `repository.<name>.`. In this example, the
+descriptor specifies the information for the `apache-Mynewt-core`.
+
+<br>
+
+The fields within the descriptor have the following definitions:
+
+* **type** -- The type of code storage the repo uses. The current version
+of `newt` only supports github. Future versions may support generic git or other
+code storage mechanisms.
+
+* **vers** -- The version of the repo to use for your project. A source
+code repository contains many versions of the source. This field is used to
+specify the one to use for this project. See the section on versions below
+for a detailed description of the format of this field.
+
+* **user** -- The username for the repo. On github, this is the name
+after `github.com` in the repo path. Consider the repository
+`https://github.com/apache/incubator-mynewt-core`. It has username `apache`.
+
+* **repo** -- The name of the repo. On github, this is the name after
+the username described above. Consider the repository
+`https://github.com/apache/incubator-mynewt-core`. It has username
+`incubator-mynewt-core`. This is a path to the source control
+and should not be confused with the name of the repo that you used in the
+`repository.<name>` declaration above. That name is contained elsewhere
+within the repo. See Below.
+
+<br>
+
+### Adding Existing Repos to my Project
+
+To add a new repo to your project, you have to complete two steps.
+
+* Edit the `project.yml` file and add a new repo descriptor. The previous
+section includes information on the field required in your repo descriptor.
+
+* Edit the `project/yml` file and add a new line to the `project.repositories`
+variable with the name of the repo you are adding.
+
+An example of a `project.yml` file with two repositories is shown below:
+
+```no-highlight
+project.name: "my_project"
+
+project.repositories:
+ - apache-Mynewt-core
+ - Mynewt_arduino_zero
+
+# Use github's distribution mechanism for core ASF libraries.
+# This provides mirroring automatically for us.
+#
+repository.apache-Mynewt-core:
+ type: github
+ vers: 0-latest
+ user: apache
+ repo: incubator-mynewt-core
+
+# a special repo to hold hardware specific stuff for arduino zero
+repository.Mynewt_arduino_zero:
+ type: github
+ vers: 0-latest
+ user: runtimeinc
+ repo: Mynewt_arduino_zero
+```
+
+<br>
+
+### What Version of the Repo to use
+
+Mynewt repos are version-ed artifacts. They are stored in source control
+systems like github. The repo descriptor in your `project.yml` file must
+specify the version of the repo you will accept into your project.
+
+For now, we are at the beginnings of Mynewt. For testing and evaluation
+please use `0-latest` in the `vers` field in your repo descriptor.
+
+```
+ vers:0-latest
+```
+
+See [Create a Repo](create_repo) for a description of the versioning system and all the possible ways to specify a version to use.
+
+<br>
+
+### Identifying a Repo
+
+A repo contains Mynewt packages organized in a specific way and stored in one of the supported code storage methods described above. In other words, it is a Mynewt project with an additional file `repository.yml` which describes the repo for use by `newt` (and humans browsing them). It contains a mapping of version numbers to the actual github branches containing the source code.
+
+Note that the `repository.yml` file lives only in the master branch of the git
+repository. `Newt` will always fetch this file from the master branch and then
+use that to determine the actual branch required depending on the version
+specified in your `project.yml` file. Special care should be taken to ensure that this file exists only in the master branch.
+
+Here is the `repository.yml` file from the apache-Mynewt-core:
+
+```no-highlight
+repo.name: apache-mynewt-core
+repo.versions:
+ "0.7.9": "Mynewt_0_8_0_b2_tag"
+ "0-latest": "0.7.9"
+ "0.8-latest": "0.7.9"
+```
+
+<br>
+
+It contains the following:
+
+* **repo.name** The external name that is used to include the library in
+your `project.yml` file. This is the name you in include in the `project.repositories` variable when adding this repository to your project.
+* **repo.versions** A description of what versions to give the user depending
+on the settings in their `project.yml` file.
+
+<br>
+
+### Repo Version
+
+The repo version number resolves to an actual git branch depending on the mapping specified in `repository.yml` for that repo. The version field argument in your `project.yml` file supports multiple formats for flexibility:
+
+```no-highlight
+<major_num>.<minor_num>.<revision_num>
+```
+
+or
+
+```no-highlight
+<major_num>.<minor_num>-<stability string>
+```
+
+or
+
+```no-highlight
+<major_num>-<stability string>
+```
+
+<br>
+
+The stability string can be one of 3 pre-defined stability values.
+
+1. stable -- A stable release version of the repository
+2. dev -- A development version from the repository
+3. latest -- The latest from the repository
+
+In your `project.yml` file you can specify different combinations of
+the version number and stability value. For example:
+
+* `0-latest` -- The latest version with major number 0
+* `1.2-stable` -- The latest stable version with major and minor number 1.2
+* `1.2-dev` -- The development version from 1.2
+* `1.1.1` -- a specific version 1.1.1
+
+You cannot specify a stability string with a fully numbered version, e.g.
+
+```no-highlight
+1.2.8-stable
+```
+
+<br>
+
+### Repo Versions Available
+
+A `repository.yml` file contains information to match a version request
+into a git branch to fetch for your project.
+
+It's up to the repository maintainer to map these to branches of the
+repository. For example, let's say in a fictitious repository the following are
+defined.
+
+```no-highlight
+repo.versions:
+ "0.8.0": "xxx_branch_0_8_0"
+ "1.0.0": "xxx_branch_1_0_0"
+ "1.0.2": "xxx_branch_1_0_2"
+ "1.1.1": "xxx_branch_1_1_0"
+ "1.1.2": "xxx_branch_1_1_2"
+ "1.2.0": "xxx_branch_1_2_0"
+ "1.2.1": "xxx_branch_1_2_1"
+ "1.2-dev": "1.2.1"
+ "1-dev": "1.2-dev"
+ "1.2-stable": "1.2.0"
+ "0-latest": "0.8.0"
+ "1-latest": "1-dev"
+ ....
+```
+
+When the `project.yml` file asks for `1.2-stable` it is resolved to version
+`1.2.0` (perhaps `1.2.1` is not stable yet), which in turn resolves to a specific
+branch `xxx_branch_1_2_0`. This is the branch that `newt` fetches into
+your project.
+
+**Note:** Make sure a repo version exists in the `repository.yml` file of a repo you wish to add. Otherwise Newt will not be able to resolve the version and will fail to fetch the repo into your project.
+
+<br>
+
+### How to find out what Repos are available for Mynewt components
+
+Currently, there is no `newt` command to locate/search Mynewt package
+repositories. However, since the `newt` tool supports only github,
+searching github by keyword is a satisfactory option until a search
+tool is created.
+
+When searching github, recall that a Mynewt repository must
+have a `repository.yml` file in its root directory. If you don't see
+that file, it's not a Mynewt repository and can't be included in your
+project via the newt tool.
+
+Once you find a repository, the github URL and `repository.yml` file
+should give you all the information to add it to your `project.yml` file.
+
+<br>
+
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b55ab2bc/docs/os/tutorials/repo/create_repo.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/repo/create_repo.md b/docs/os/tutorials/repo/create_repo.md
new file mode 100644
index 0000000..1e1927e
--- /dev/null
+++ b/docs/os/tutorials/repo/create_repo.md
@@ -0,0 +1,172 @@
+## Create a Repo out of a Project
+
+In order to create a repository out of a project, all you need to do is create a `repository.yml` file, and check it into the master branch of your project.
+
+**NOTE:** Currently only github source control service is supported by our package management system, but support for plain git will be added soon.
+
+The repository.yml defines all versions of the repository and the corresponding source control tags that these versions correspond to. As an example, if the repository.yml file has the following content, it means there is one version of the apache-mynewt-core operating system available, which is `0.0.0` (implying we haven't released yet!). Such a version number corresponds to the "develop" branch in this repository. `0-latest` would also resolved to this same `0.0.0` version. The next section explains the versioning system a bit more.
+
+```
+$ more repository.yml
+repo.name: apache-mynewt-core
+repo.versions:
+ "0.0.0": "develop"
+ "0-latest": "0.0.0"
+```
+
+<br>
+
+### Where should the repository.yml file be?
+
+The `repository.yml` file lives only in the master branch of the git
+repository. `Newt` will always fetch this file from the master branch and then
+use that to resolve the actual branch required depending on the version
+specified in the project. **Special care should be taken to ensure that this
+file exists only in the master branch.**
+
+Here is the `repository.yml` file from a certain snapshot of apache-Mynewt-core:
+
+```
+repo.name: apache-mynewt-core
+repo.versions:
+ "0.7.9": "Mynewt_0_8_0_b2_tag"
+ "0-latest": "0.7.9"
+ "0.8-latest": "0.7.9"
+```
+
+<br>
+
+It contains the following:
+
+* **repo.name** The external name that is used to include the library in
+your `project.yml` file. This is the name you in include in the `project.repositories` variable when adding this repository to your project.
+* **repo.versions** A description of what versions to give the user depending
+on the settings in their `project.yml` file. See below for a thorough description
+on versioning. Its a flexible mapping between version numbers and git branches.
+
+<br>
+
+### Repo Version Specification
+
+The version field argument for a repo has the following format:
+
+```no-highlight
+<major_num>.<minor_num>.<revision_num>
+```
+
+or
+
+```no-highlight
+<major_num>.<minor_num>-<stability string>
+```
+
+or
+
+```no-highlight
+<major_num>-<stability string>
+```
+
+<br>
+
+The stability string can be one of 3 pre-defined stability values.
+
+1. stable -- A stable release version of the repository
+2. dev -- A development version from the repository
+3. latest -- The latest from the repository
+
+In your `project.yml` file you can specify different combinations of
+the version number and stability value. For example:
+
+* `0-latest` -- The latest version with major number 0
+* `1.2-stable` -- The latest stable version with major and minor number 1.2
+* `1.2-dev` -- The development version from 1.2
+* `1.1.1` -- a specific version 1.1.1
+
+You **cannot** specify a stability string with a fully numbered version, e.g.
+
+```no-highlight
+1.2.8-stable
+```
+
+<br>
+
+### Repo Version Resolution
+
+A `repository.yml` file contains information to match this version request
+into a git branch to fetch for your project.
+
+It's up to you as the repository maintainer to map these to actual github branches of the repository. For example, let's say in a fictitious repository the following are defined.
+
+```no-highlight
+repo.versions:
+ "0.8.0": "xxx_branch_0_8_0"
+ "1.0.0": "xxx_branch_1_0_0"
+ "1.0.2": "xxx_branch_1_0_2"
+ "1.1.1": "xxx_branch_1_1_0"
+ "1.1.2": "xxx_branch_1_1_2"
+ "1.2.0": "xxx_branch_1_2_0"
+ "1.2.1": "xxx_branch_1_2_1"
+ "1.2-dev": "1.2.1"
+ "1-dev": "1.2-dev"
+ "1.2-stable": "1.2.0"
+ "0-latest": "0.8.0"
+ "1-latest": "1-dev"
+ ....
+```
+
+When the `project.yml` file asks for `1.2-stable` it will be resolved to version
+`1.2.0` which in turn will resolve to a specific branch `xxx_branch_1_2_0`. This is the branch that `newt` will fetch into the project with that `project.yml` file.
+
+<br>
+
+### Dependencies on other repos
+
+Repositories can also have dependencies on other repositories. These
+dependencies should be listed out on a per-tag basis. So, for example,
+if apache-mynewt-core were to depend on sterlys-little-repo, you might
+have the following directives in the repository.yml:
+
+```
+develop.repositories:
+ sterlys-little-repo:
+ type: github
+ vers: 0.8-latest
+ user: sterlinghughes
+ repo: sterlys-little-repo
+```
+
+<br>
+
+This would tell Newt that for anything that resolves to the develop
+branch, this repository requires the sterlys-little-repo repository.
+
+Dependencies are resolved circularly by the newt tool, and every dependent repository is placed as a sibling in the repos directory. Currently, if two repositories have the same name, they will conflict and bad things will happen.
+
+When a repository is installed to the repos/ directory, the current
+version of that repository is written to the "project.state" file. The
+project state file contains the currently installed version of any given
+repository. This way, the current set of repositories can be recreated
+from the project.state file reliably, whereas the project.yml file can
+have higher level directives (i.e. include 0.8-stable.)
+
+
+### Resolving dependencies
+
+At the moment, all dependencies must match, otherwise newt will provide
+an error. As an example, if you have a set of dependencies such that:
+
+```
+apache-mynewt-core depends on sterlys-little-repo 0.6-stable
+apache-mynewt-core depends on sterlys-big-repo 0.5.1
+sterlys-big-repo-0.5.1 depends on sterlys-little-repo 0.6.2
+```
+
+<br>
+
+where 0.6-stable is 0.6.3, the newt tool will try and resolve the dependency to
+sterlys-little-repo. It will notice that there are two conflicting
+versions of the same repository, and not perform installation.
+
+In the future Newt will be smarter about loading in all dependencies,
+and then looking to satisfy those dependencies to the best match of all
+potential options.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b55ab2bc/docs/os/tutorials/repo/upgrade_repo.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/repo/upgrade_repo.md b/docs/os/tutorials/repo/upgrade_repo.md
new file mode 100644
index 0000000..c44fab8
--- /dev/null
+++ b/docs/os/tutorials/repo/upgrade_repo.md
@@ -0,0 +1,14 @@
+## Upgrade a repo
+
+In order to upgrade a previously installed repository, the "newt upgrade" command should be issued:
+
+```
+$ newt upgrade
+```
+
+<br>
+
+Newt upgrade will look at the current desired version in `project.yml`,
+and compare it to the version in `project.state`. If these two differ, it
+will upgrade the dependency. Upgrade works not just for the dependency
+in `project.yml`, but for all the sub-dependencies that they might have.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b55ab2bc/docs/os/tutorials/upgrade_repo.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/upgrade_repo.md b/docs/os/tutorials/upgrade_repo.md
deleted file mode 100644
index c44fab8..0000000
--- a/docs/os/tutorials/upgrade_repo.md
+++ /dev/null
@@ -1,14 +0,0 @@
-## Upgrade a repo
-
-In order to upgrade a previously installed repository, the "newt upgrade" command should be issued:
-
-```
-$ newt upgrade
-```
-
-<br>
-
-Newt upgrade will look at the current desired version in `project.yml`,
-and compare it to the version in `project.state`. If these two differ, it
-will upgrade the dependency. Upgrade works not just for the dependency
-in `project.yml`, but for all the sub-dependencies that they might have.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b55ab2bc/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index 42d213c..167742c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -30,15 +30,16 @@ pages:
- 'Blinky on STM32F303': 'os/tutorials/STM32F303.md'
- 'Blinky on nRF52': 'os/tutorials/nRF52.md'
- 'Run Blinky from SRAM, no bootloader': 'os/tutorials/blinky_sram_olimex.md'
- - 'Add repo to project': 'os/tutorials/add_repos.md'
- - 'Create a repo': 'os/tutorials/create_repo.md'
- - 'Upgrade a repo': 'os/tutorials/upgrade_repo.md'
- - 'Use BLE app to check stats via console': 'os/tutorials/bletiny_project.md'
- - 'Enable remote comms on sim device': 'os/tutorials/project-slinky.md'
- - 'Enable remote comms on STM32 board': 'os/tutorials/project-target-slinky.md'
+ - 'Work with repositories':
+ - toc: 'os/tutorials/repo/add_repos.md'
+ - 'Upgrade a repo': 'os/tutorials/repo/upgrade_repo.md'
+ - 'Turn project into a repo': 'os/tutorials/repo/create_repo.md'
- 'Write a Test Suite for a Package': 'os/tutorials/unit_test.md'
- 'Air-quality Sensor project': 'os/tutorials/air_quality_sensor.md'
- 'Add task to manage multiple events': 'os/tutorials/event_queue.md'
+ - 'Enable remote comms on sim device': 'os/tutorials/project-slinky.md'
+ - 'Enable remote comms on STM32 board': 'os/tutorials/project-target-slinky.md'
+ - 'BLE app to check stats via console': 'os/tutorials/bletiny_project.md'
- 'BLE peripheral project':
- toc: 'os/tutorials/bleprph/bleprph-intro.md'
- 'Service Registration': 'os/tutorials/bleprph/bleprph-svc-reg.md'
@@ -46,6 +47,7 @@ pages:
- 'Advertising': 'os/tutorials/bleprph/bleprph-adv.md'
- 'Connection Callbacks': 'os/tutorials/bleprph/bleprph-conn.md'
- 'BLE iBeacon': 'os/tutorials/ibeacon.md'
+ - 'BLE HCI interface': 'os/tutorials/blehci_project.md'
- OS User Guide:
- toc: 'os/os_user_guide.md'
- OS Core: