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/19 08:00:46 UTC
[1/7] incubator-mynewt-site git commit: Fix case inconsistency in
filename (problem for non-mac).
Repository: incubator-mynewt-site
Updated Branches:
refs/heads/master dcf6bf05f -> 50ed85c99
Fix case inconsistency in filename (problem for non-mac).
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/06b2c1c8
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/06b2c1c8
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/06b2c1c8
Branch: refs/heads/master
Commit: 06b2c1c80650f1fe021fcb4a9ac05586d8c19fb6
Parents: 9be2bd9
Author: Christopher Collins <cc...@apache.org>
Authored: Thu Mar 17 17:59:24 2016 -0700
Committer: Christopher Collins <cc...@apache.org>
Committed: Thu Mar 17 18:06:51 2016 -0700
----------------------------------------------------------------------
docs/os/tutorials/Olimex.md | 318 ---------------------------------------
docs/os/tutorials/olimex.md | 318 +++++++++++++++++++++++++++++++++++++++
2 files changed, 318 insertions(+), 318 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/06b2c1c8/docs/os/tutorials/Olimex.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/Olimex.md b/docs/os/tutorials/Olimex.md
deleted file mode 100644
index 0172188..0000000
--- a/docs/os/tutorials/Olimex.md
+++ /dev/null
@@ -1,318 +0,0 @@
-## Blinky, Your Hello World!
-
-### Objective
-
-Learn how to use packages from a default application repository of Mynewt to build your first *Hello World* application (Blinky) on a target board. Once built using the *newt* tool, this application will blink the LED lights on the target board. Fun stuff!
-
-This tutorial will guide you to achieve the following, assuming you have already set up the environment on your computer to use Mynewt OS and newt tool:
-
-* Download packages and use tools to create a runtime image for a board to make its LED blink. You have two choices here:
- * [Download an image to SRAM](#use-sram-to-make-led-blink), or
- * [Download it to flash](#use-flash-to-make-led-blink).
-
-<br>
-
-** Time Requirement**: Allow yourself a couple of hours for this project if you are relatively new to embedded systems and playing with development boards. Those jumpers can be pesky!
-
-<br>
-
-### What you need
-
-1. STM32-E407 development board from Olimex. You can order it from [http://www.mouser.com](http://www.mouser.com/ProductDetail/Olimex-Ltd/STM32-E407/?qs=UN6GZl1KCcit6Ye0xmPO4A%3D%3D), [http://www.digikey.com](http://www.digikey.com/product-detail/en/STM32-E407/1188-1093-ND/3726951), and other places.
-2. ARM-USB-TINY-H connector with JTAG interface for debugging ARM microcontrollers (comes with the ribbon cable to hook up to the board)
-3. USB A-B type cable to connect the debugger to your personal computer
-4. Personal Computer with Mac OS (Mac: OS X Yosemite Version 10.10.5) or Linux box (Ubuntu 14.10: Utopic Unicorn)
-5. An account on Github repository and *git* installed on your computer.
-6. It is assumed you have already installed newt tool.
-7. It is assumed you already installed native tools as described [here](../get_started/native_tools.md)
-
-Also, we assume that you're familiar with UNIX shells. Let's gets started!
-
-<br>
-
-
-### Use SRAM to make LED blink
-
-If you wish to build the image to run from the onboard SRAM on Olimex board, follow the steps below:
-
-<br>
-
-#### Prepare the Software
-
-* Make sure the PATH environment variable includes the $HOME/dev/go/bin directory.
-
-<br>
-
-#### Create a project.
-
-Create a new project to hold your work. For a deeper understanding, you can read about project creation in
-[Get Started -- Creating Your First Project](../get_started/project_create.md)
-or just follow the commands below.
-
-```no-highlight
- $ mkdir ~/dev
- $ cd ~/dev
- $ newt new myproj
- Downloading project skeleton from apache/incubator-mynewt-blinky...
- Installing skeleton in myproj...
- Project myproj successfully created.
-
- $cd myproj
-
- $ newt install -v
- apache-mynewt-core
- Downloading repository description for apache-mynewt-core... success!
- ...
- apache-mynewt-core successfully installed version 0.7.9-none
-```
-
-<br>
-
-#### Create a target
-
-Change directory to ~/dev/myproj directory and define the *blinky* target inside myproj, using the *newt* tool. Starting with the target name, assign specific aspects of the project, as shown below, to pull the appropriate packages and build the right bundle or list for the board. For example, we set the build_profile, board support package (bsp), and app.
-
-
-```no-highlight
- $ newt target create blinky
- $ newt target set blinky build_profile=debug
- $ newt target set blinky bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard
- $ newt target set blinky app=apps/blinky
- $ newt target show blinky
- targets/boot_olimex
- app=apps/blinky
- bsp=hw/bsp/olimex_stm32-e407_devboard
- build_profile=debug
-```
-
-<br>
-
-#### Build the image
-
-Next, let's build the image with the above values assigned. By default, the linker script within the `hw/bsp/olimex_stm32-e407_devboard` package builds an image for flash memory, which we don't want; instead, we want an image for the SRAM, so you need to switch that script with `run_from_sram.ld`.
-
-<font color="red">
-(We are working to simplify this scheme whereby an executable for a project will correctly elect the linker scripts and generate the relevant image. For example, the scheme will key on project identity such as bootloader, RAM, Flash (default) and build accordingly.) </font>.
-
-Afer you build the target, you can find the executable *blinky.elf* in the project directory *~/dev/myproj/bin/blinky/apps/blinky/.*
-
-
-```no-highlight
- $ cd ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/
- $ diff olimex_stm32-e407_devboard.ld run_from_sram.ld
- (some diff will be displayed)
- $ cp run_from_sram.ld olimex_stm32-e407_devboard.ld
- $ cd ~/dev/myproj
- $ newt build blinky
- Compiling case.c
- Compiling suite.c
- ...
- Linking blinky.elf
- App successfully built:~/dev/myproj/bin/blinky/apps/blinky/blinky.elf
- $ ls ~/dev/myproj/bin/blinky/apps/blinky/
- blinky.elf blinky.elf.bin blinky.elf.cmd
- blinky.elf.lst blinky.elf.map
-```
-
-<br>
-
-#### Prepare the hardware to boot from embedded SRAM
-
-* Locate the boot jumpers on the board.
-
-<br>
-
-
-
-
-<br>
-
-* B1_1/B1_0 and B0_1/B0_0 are PTH jumpers. Note that because the markings on the board may not always be accurate, when in doubt, you should always refer to the manual for the correct positioning. Since the jumpers are a pair, they should move together, and as such, the pair is responsible for the boot mode when bootloader is present.
-To locate the bootloader, the board searches in three places: User Flash Memory, System Memory or the Embedded SRAM. For this Blinky project, we will configure it to boot from SRAM by jumpering **B0_1** and **B1_1**.
-
-* Connect USB-OTG#2 in the picture above to a USB port on your computer (or a powered USB hub to make sure there is enough power available to the board).
-
-* The red PWR LED should be lit.
-
-* Connect the JTAG connector to the SWD/JTAG interface on the board. The other end of the cable should be connected to the USB port or hub of your computer.
-
-<br>
-
-#### Let's Go!
-
-* Ensure that you are in the blinky project directory with the *blinky.elf* executable. Run the debug command in the *newt* tool. You'll see some status messages as shown below. In case you need to halt the debugging session, you can issue an `-c "reset halt"` command.
-```no-highlight
- $ cd ~/dev/core
- $ newt debug blinky
- Debugging with ~/dev/core/hw/bsp/olimex_...
- Debugging ~/dev/core/project/blinky/bin/blinky/blinky.elf
- GNU gdb (GNU Tools for ARM Embedded Processors) 7.8.0.20150604-cvs
- Copyright (C) 2014 Free Software Foundation, Inc.
- License GPLv3+: GNU GPL version 3 <http://gnu.org/licenses/gpl.html>
- ...
- (info)
- ...
- target state: halted
- target halted due to debug-request, current mode: Thread
- xPSR: 0x01000000 pc: 0x080003c0 msp: 0x10010000
- Info : accepting 'gdb' connection on tcp/3333
- Info : device id = 0x10036413
- Info : flash size = 1024kbytes
-```
-<br>
-
-Check the value of the msp (main service pointer) register. If it is not 0x10010000 as indicated above, you will have to manually set it after you open the gdb tool and load the image on it. For example,
-
-```no-highlight
- (gdb) set $msp=0x10010000
-```
-
-<br>
-
- Now load the image and type "c" or "continue" from the GNU debugger.
-
-```no-highlight
- (gdb) load ~/dev/myproj/bin/blinky/apps/blinky/blinky.elf
- Loading section .text, size 0x16b88 lma 0x20000000
- Loading section .ARM.exidx, size 0x18 lma 0x20016b88
- Loading section .data, size 0x9ec lma 0x20016ba0
- Start address 0x200004b8, load size 95628
- Transfer rate: 74 KB/sec, 3825 bytes/write.
- (gdb) c
- Continuing.
-```
-
-* Voilà! The board's LED should be blinking at 1 Hz. Success!
-
-<br>
-
-### Use flash to make LED blink
-
-If you wish to build the image to run from the onboard flash memory on Olimex board, follow the steps below:
-
-* Configure the board to boot from flash by moving the two jumpers together to **B0_0** and **B1_0**. Refer to the pictures of the board under the section titled ["Prepare the hardware to boot from embedded SRAM"](#prepare-the-hardware-to-boot-from-embedded-sram).
-
- You will have to reset the board once the image is uploaded to it.
-
-* If you skipped the first option for the project [(downloading an image to SRAM)](#use-sram-to-make-led-blink), then skip this step. Otherwise, continue with this step.
-
- By default, the linker script (`olimex_stm32-e407_devboard.ld`) is configured to run from bootloader and flash. However, if you first ran the image from SRAM you had changed `olimex_stm32-e407_devboard.ld` to match `run_from_sram.ld`. You will, therefore, return to defaults with `olimex_stm32-e407_devboard.ld` linker script matching the contents of 'run_from_loader.ld'. Return to the project directory.
-
-```no-highlight
-$ cd ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/
-$ diff olimex_stm32-e407_devboard.ld run_from_sram.ld
-$ diff olimex_stm32-e407_devboard.ld run_from_loader.ld
-(some diff will be displayed)
-$ cp run_from_loader.ld olimex_stm32-e407_devboard.ld
-$ cd ~/dev/myproj
-```
-
-<br>
-
-* In order to run the image from flash, you need to build the bootloader as well. The bootloader does the initial set up of the Olimex board and then transfers control to the image stored at a location in flash known to it.
-
-Let's create boot_olimex:
-
-```no-highlight
- $ newt target create boot_olimex
- $ newt target set boot_olimex build_profile=optimized
- $ newt target set boot_olimex bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard
- $ newt target set boot_olimex app=@apache-mynewt-core/apps/boot
- $ newt target show boot_olimex
- targets/boot_olimex
- app=app=@apache-mynewt-core/apps/boot
- bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboar
- build_profile=optimized
-```
-
-<br>
-
-* Now let's build both targets now.
-
-```no-highlight
- $ newt build boot_olimex
- ...
- App successfully built: ~/dev/myproj/bin/boot_olimex/apps/boot/boot.elf
- $ newt build blinky
- ...
- Linking blinky.elf
- App successfully built: ~/dev/myproj/bin/blinky/apps/blinky/blinky.elf
-```
-
-<br>
-
-* Create the blinky image and download the bootloader and the image to flash ... in a flash!
-When creating an image, you can assign a version number to your image; here we use '1.2.3'
-
-```no-highlight
- $ newt create-image blinky 1.2.3
- App image succesfully generated: ~/dev/myproj/bin/blinky/apps/blinky/blinky.img
- Build manifest: ~/dev/myproj/bin/blinky/apps/blinky/manifest.json
- $ newt load boot_olimex
- Downloading~/dev/myproj/bin/boot_olimex/apps/boot/boot.elf.bin to 0x08000000
- Open On-Chip Debugger 0.9.0 (2015-11-15-13:10)
- ...
- shutdown command invoked
- $ newt load blinky
- Downloading ~/dev/myproj/bin/blinky/apps/blinky/blinky.img to 0x08020000
- Open On-Chip Debugger 0.9.0 (2015-11-15-13:10)
- ...
- shutdown command invoked
-```
-
-<br>
-
-* Voilà! The LED should be blinking! Success!
-
-<br>
-
-**But wait...not so fast.** Let's double check that it is indeed booting from flash and making the LED blink from the image in flash. Pull the USB cable off the Olimex JTAG adaptor, severing the debug connection to the JTAG port. Next power off the Olimex board by pulling out the USB cable from the board. Wait for a couple of seconds and plug the USB cable back to the board.
-
- The LED light will start blinking again. Success!
-
- **Note #1:** If you want to download the image to flash and a gdb session opened up, use `newt debug blinky` after `newt download blinky`.
-
-```no-highlight
- $ newt debug blinky
- Debugging with ~/dev/myproj/hw/bsp/olimex_stm32-e407_...
- Debugging ~/dev/myproj/project/blinky/bin/blinky/blinky.elf
- GNU gdb (GNU Tools for ARM Embedded Processors) 7.8.0.20150604-cvs
- Copyright (C) 2014 Free Software Foundation, Inc.
- License GPLv3+: GNU GPL version 3 <http://gnu.org/licenses/gpl.html>
- ...
- (info)
- ...
- target state: halted
- target halted due to debug-request, current mode: Thread
- xPSR: 0x01000000 pc: 0x08000250 msp: 0x10010000
- Info : accepting 'gdb' connection from 3333
- Info : device id = 0x10036413
- Info : flash size = 1024kbytes
- Reset_Handler () at startup_STM32F40x.s:199
- 199 ldr r1, =__etext
- (gdb)
-```
-
-<br>
-
- **Note #2:** If you want to erase the flash and load the image again you may use the following commands from within gdb. `flash erase_sector 0 0 x` tells it to erase sectors 0 through x. When you ask it to display (in hex notation) the contents of the sector starting at location 'lma,' you should see all f's. The memory location 0x8000000 is the start or origin of the flash memory contents and is specified in the olimex_stm32-e407_devboard.ld linker script. The flash memory locations is specific to the processor.
-```no-highlight
- (gdb) monitor flash erase_sector 0 0 4
- erased sectors 0 through 4 on flash bank 0 in 2.296712s
- (gdb) monitor mdw 0x08000000 16
- 0x08000000: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff
- (0x08000020: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff
- (0x08000000: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff
- (0x08000020: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff
- (gdb) monitor flash info 0
-```
-
-### Conclusion
-
-Congratulations! You have now tried out a project on actual hardware. If this is your first time to embedded systems, this must feel like the best hands-on and low-level "Hello World" program ever.
-
-Good, we have more fun tutorials for you to get your hands dirty. Be bold and try other Blinky-like [tutorials](../tutorials/nRF52.md).
-
-If you see anything missing or want to send us feedback, please do so by signing up for appropriate mailing lists on our [Community Page](../../community.md)
-
-Keep on hacking and blinking!
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/06b2c1c8/docs/os/tutorials/olimex.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/olimex.md b/docs/os/tutorials/olimex.md
new file mode 100644
index 0000000..0172188
--- /dev/null
+++ b/docs/os/tutorials/olimex.md
@@ -0,0 +1,318 @@
+## Blinky, Your Hello World!
+
+### Objective
+
+Learn how to use packages from a default application repository of Mynewt to build your first *Hello World* application (Blinky) on a target board. Once built using the *newt* tool, this application will blink the LED lights on the target board. Fun stuff!
+
+This tutorial will guide you to achieve the following, assuming you have already set up the environment on your computer to use Mynewt OS and newt tool:
+
+* Download packages and use tools to create a runtime image for a board to make its LED blink. You have two choices here:
+ * [Download an image to SRAM](#use-sram-to-make-led-blink), or
+ * [Download it to flash](#use-flash-to-make-led-blink).
+
+<br>
+
+** Time Requirement**: Allow yourself a couple of hours for this project if you are relatively new to embedded systems and playing with development boards. Those jumpers can be pesky!
+
+<br>
+
+### What you need
+
+1. STM32-E407 development board from Olimex. You can order it from [http://www.mouser.com](http://www.mouser.com/ProductDetail/Olimex-Ltd/STM32-E407/?qs=UN6GZl1KCcit6Ye0xmPO4A%3D%3D), [http://www.digikey.com](http://www.digikey.com/product-detail/en/STM32-E407/1188-1093-ND/3726951), and other places.
+2. ARM-USB-TINY-H connector with JTAG interface for debugging ARM microcontrollers (comes with the ribbon cable to hook up to the board)
+3. USB A-B type cable to connect the debugger to your personal computer
+4. Personal Computer with Mac OS (Mac: OS X Yosemite Version 10.10.5) or Linux box (Ubuntu 14.10: Utopic Unicorn)
+5. An account on Github repository and *git* installed on your computer.
+6. It is assumed you have already installed newt tool.
+7. It is assumed you already installed native tools as described [here](../get_started/native_tools.md)
+
+Also, we assume that you're familiar with UNIX shells. Let's gets started!
+
+<br>
+
+
+### Use SRAM to make LED blink
+
+If you wish to build the image to run from the onboard SRAM on Olimex board, follow the steps below:
+
+<br>
+
+#### Prepare the Software
+
+* Make sure the PATH environment variable includes the $HOME/dev/go/bin directory.
+
+<br>
+
+#### Create a project.
+
+Create a new project to hold your work. For a deeper understanding, you can read about project creation in
+[Get Started -- Creating Your First Project](../get_started/project_create.md)
+or just follow the commands below.
+
+```no-highlight
+ $ mkdir ~/dev
+ $ cd ~/dev
+ $ newt new myproj
+ Downloading project skeleton from apache/incubator-mynewt-blinky...
+ Installing skeleton in myproj...
+ Project myproj successfully created.
+
+ $cd myproj
+
+ $ newt install -v
+ apache-mynewt-core
+ Downloading repository description for apache-mynewt-core... success!
+ ...
+ apache-mynewt-core successfully installed version 0.7.9-none
+```
+
+<br>
+
+#### Create a target
+
+Change directory to ~/dev/myproj directory and define the *blinky* target inside myproj, using the *newt* tool. Starting with the target name, assign specific aspects of the project, as shown below, to pull the appropriate packages and build the right bundle or list for the board. For example, we set the build_profile, board support package (bsp), and app.
+
+
+```no-highlight
+ $ newt target create blinky
+ $ newt target set blinky build_profile=debug
+ $ newt target set blinky bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard
+ $ newt target set blinky app=apps/blinky
+ $ newt target show blinky
+ targets/boot_olimex
+ app=apps/blinky
+ bsp=hw/bsp/olimex_stm32-e407_devboard
+ build_profile=debug
+```
+
+<br>
+
+#### Build the image
+
+Next, let's build the image with the above values assigned. By default, the linker script within the `hw/bsp/olimex_stm32-e407_devboard` package builds an image for flash memory, which we don't want; instead, we want an image for the SRAM, so you need to switch that script with `run_from_sram.ld`.
+
+<font color="red">
+(We are working to simplify this scheme whereby an executable for a project will correctly elect the linker scripts and generate the relevant image. For example, the scheme will key on project identity such as bootloader, RAM, Flash (default) and build accordingly.) </font>.
+
+Afer you build the target, you can find the executable *blinky.elf* in the project directory *~/dev/myproj/bin/blinky/apps/blinky/.*
+
+
+```no-highlight
+ $ cd ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/
+ $ diff olimex_stm32-e407_devboard.ld run_from_sram.ld
+ (some diff will be displayed)
+ $ cp run_from_sram.ld olimex_stm32-e407_devboard.ld
+ $ cd ~/dev/myproj
+ $ newt build blinky
+ Compiling case.c
+ Compiling suite.c
+ ...
+ Linking blinky.elf
+ App successfully built:~/dev/myproj/bin/blinky/apps/blinky/blinky.elf
+ $ ls ~/dev/myproj/bin/blinky/apps/blinky/
+ blinky.elf blinky.elf.bin blinky.elf.cmd
+ blinky.elf.lst blinky.elf.map
+```
+
+<br>
+
+#### Prepare the hardware to boot from embedded SRAM
+
+* Locate the boot jumpers on the board.
+
+<br>
+
+
+
+
+<br>
+
+* B1_1/B1_0 and B0_1/B0_0 are PTH jumpers. Note that because the markings on the board may not always be accurate, when in doubt, you should always refer to the manual for the correct positioning. Since the jumpers are a pair, they should move together, and as such, the pair is responsible for the boot mode when bootloader is present.
+To locate the bootloader, the board searches in three places: User Flash Memory, System Memory or the Embedded SRAM. For this Blinky project, we will configure it to boot from SRAM by jumpering **B0_1** and **B1_1**.
+
+* Connect USB-OTG#2 in the picture above to a USB port on your computer (or a powered USB hub to make sure there is enough power available to the board).
+
+* The red PWR LED should be lit.
+
+* Connect the JTAG connector to the SWD/JTAG interface on the board. The other end of the cable should be connected to the USB port or hub of your computer.
+
+<br>
+
+#### Let's Go!
+
+* Ensure that you are in the blinky project directory with the *blinky.elf* executable. Run the debug command in the *newt* tool. You'll see some status messages as shown below. In case you need to halt the debugging session, you can issue an `-c "reset halt"` command.
+```no-highlight
+ $ cd ~/dev/core
+ $ newt debug blinky
+ Debugging with ~/dev/core/hw/bsp/olimex_...
+ Debugging ~/dev/core/project/blinky/bin/blinky/blinky.elf
+ GNU gdb (GNU Tools for ARM Embedded Processors) 7.8.0.20150604-cvs
+ Copyright (C) 2014 Free Software Foundation, Inc.
+ License GPLv3+: GNU GPL version 3 <http://gnu.org/licenses/gpl.html>
+ ...
+ (info)
+ ...
+ target state: halted
+ target halted due to debug-request, current mode: Thread
+ xPSR: 0x01000000 pc: 0x080003c0 msp: 0x10010000
+ Info : accepting 'gdb' connection on tcp/3333
+ Info : device id = 0x10036413
+ Info : flash size = 1024kbytes
+```
+<br>
+
+Check the value of the msp (main service pointer) register. If it is not 0x10010000 as indicated above, you will have to manually set it after you open the gdb tool and load the image on it. For example,
+
+```no-highlight
+ (gdb) set $msp=0x10010000
+```
+
+<br>
+
+ Now load the image and type "c" or "continue" from the GNU debugger.
+
+```no-highlight
+ (gdb) load ~/dev/myproj/bin/blinky/apps/blinky/blinky.elf
+ Loading section .text, size 0x16b88 lma 0x20000000
+ Loading section .ARM.exidx, size 0x18 lma 0x20016b88
+ Loading section .data, size 0x9ec lma 0x20016ba0
+ Start address 0x200004b8, load size 95628
+ Transfer rate: 74 KB/sec, 3825 bytes/write.
+ (gdb) c
+ Continuing.
+```
+
+* Voilà! The board's LED should be blinking at 1 Hz. Success!
+
+<br>
+
+### Use flash to make LED blink
+
+If you wish to build the image to run from the onboard flash memory on Olimex board, follow the steps below:
+
+* Configure the board to boot from flash by moving the two jumpers together to **B0_0** and **B1_0**. Refer to the pictures of the board under the section titled ["Prepare the hardware to boot from embedded SRAM"](#prepare-the-hardware-to-boot-from-embedded-sram).
+
+ You will have to reset the board once the image is uploaded to it.
+
+* If you skipped the first option for the project [(downloading an image to SRAM)](#use-sram-to-make-led-blink), then skip this step. Otherwise, continue with this step.
+
+ By default, the linker script (`olimex_stm32-e407_devboard.ld`) is configured to run from bootloader and flash. However, if you first ran the image from SRAM you had changed `olimex_stm32-e407_devboard.ld` to match `run_from_sram.ld`. You will, therefore, return to defaults with `olimex_stm32-e407_devboard.ld` linker script matching the contents of 'run_from_loader.ld'. Return to the project directory.
+
+```no-highlight
+$ cd ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/
+$ diff olimex_stm32-e407_devboard.ld run_from_sram.ld
+$ diff olimex_stm32-e407_devboard.ld run_from_loader.ld
+(some diff will be displayed)
+$ cp run_from_loader.ld olimex_stm32-e407_devboard.ld
+$ cd ~/dev/myproj
+```
+
+<br>
+
+* In order to run the image from flash, you need to build the bootloader as well. The bootloader does the initial set up of the Olimex board and then transfers control to the image stored at a location in flash known to it.
+
+Let's create boot_olimex:
+
+```no-highlight
+ $ newt target create boot_olimex
+ $ newt target set boot_olimex build_profile=optimized
+ $ newt target set boot_olimex bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard
+ $ newt target set boot_olimex app=@apache-mynewt-core/apps/boot
+ $ newt target show boot_olimex
+ targets/boot_olimex
+ app=app=@apache-mynewt-core/apps/boot
+ bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboar
+ build_profile=optimized
+```
+
+<br>
+
+* Now let's build both targets now.
+
+```no-highlight
+ $ newt build boot_olimex
+ ...
+ App successfully built: ~/dev/myproj/bin/boot_olimex/apps/boot/boot.elf
+ $ newt build blinky
+ ...
+ Linking blinky.elf
+ App successfully built: ~/dev/myproj/bin/blinky/apps/blinky/blinky.elf
+```
+
+<br>
+
+* Create the blinky image and download the bootloader and the image to flash ... in a flash!
+When creating an image, you can assign a version number to your image; here we use '1.2.3'
+
+```no-highlight
+ $ newt create-image blinky 1.2.3
+ App image succesfully generated: ~/dev/myproj/bin/blinky/apps/blinky/blinky.img
+ Build manifest: ~/dev/myproj/bin/blinky/apps/blinky/manifest.json
+ $ newt load boot_olimex
+ Downloading~/dev/myproj/bin/boot_olimex/apps/boot/boot.elf.bin to 0x08000000
+ Open On-Chip Debugger 0.9.0 (2015-11-15-13:10)
+ ...
+ shutdown command invoked
+ $ newt load blinky
+ Downloading ~/dev/myproj/bin/blinky/apps/blinky/blinky.img to 0x08020000
+ Open On-Chip Debugger 0.9.0 (2015-11-15-13:10)
+ ...
+ shutdown command invoked
+```
+
+<br>
+
+* Voilà! The LED should be blinking! Success!
+
+<br>
+
+**But wait...not so fast.** Let's double check that it is indeed booting from flash and making the LED blink from the image in flash. Pull the USB cable off the Olimex JTAG adaptor, severing the debug connection to the JTAG port. Next power off the Olimex board by pulling out the USB cable from the board. Wait for a couple of seconds and plug the USB cable back to the board.
+
+ The LED light will start blinking again. Success!
+
+ **Note #1:** If you want to download the image to flash and a gdb session opened up, use `newt debug blinky` after `newt download blinky`.
+
+```no-highlight
+ $ newt debug blinky
+ Debugging with ~/dev/myproj/hw/bsp/olimex_stm32-e407_...
+ Debugging ~/dev/myproj/project/blinky/bin/blinky/blinky.elf
+ GNU gdb (GNU Tools for ARM Embedded Processors) 7.8.0.20150604-cvs
+ Copyright (C) 2014 Free Software Foundation, Inc.
+ License GPLv3+: GNU GPL version 3 <http://gnu.org/licenses/gpl.html>
+ ...
+ (info)
+ ...
+ target state: halted
+ target halted due to debug-request, current mode: Thread
+ xPSR: 0x01000000 pc: 0x08000250 msp: 0x10010000
+ Info : accepting 'gdb' connection from 3333
+ Info : device id = 0x10036413
+ Info : flash size = 1024kbytes
+ Reset_Handler () at startup_STM32F40x.s:199
+ 199 ldr r1, =__etext
+ (gdb)
+```
+
+<br>
+
+ **Note #2:** If you want to erase the flash and load the image again you may use the following commands from within gdb. `flash erase_sector 0 0 x` tells it to erase sectors 0 through x. When you ask it to display (in hex notation) the contents of the sector starting at location 'lma,' you should see all f's. The memory location 0x8000000 is the start or origin of the flash memory contents and is specified in the olimex_stm32-e407_devboard.ld linker script. The flash memory locations is specific to the processor.
+```no-highlight
+ (gdb) monitor flash erase_sector 0 0 4
+ erased sectors 0 through 4 on flash bank 0 in 2.296712s
+ (gdb) monitor mdw 0x08000000 16
+ 0x08000000: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff
+ (0x08000020: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff
+ (0x08000000: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff
+ (0x08000020: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff
+ (gdb) monitor flash info 0
+```
+
+### Conclusion
+
+Congratulations! You have now tried out a project on actual hardware. If this is your first time to embedded systems, this must feel like the best hands-on and low-level "Hello World" program ever.
+
+Good, we have more fun tutorials for you to get your hands dirty. Be bold and try other Blinky-like [tutorials](../tutorials/nRF52.md).
+
+If you see anything missing or want to send us feedback, please do so by signing up for appropriate mailing lists on our [Community Page](../../community.md)
+
+Keep on hacking and blinking!
[7/7] incubator-mynewt-site git commit: Cleaned up links and
instructions in Quick Start or getting started lessons. This closes #61
Posted by ad...@apache.org.
Cleaned up links and instructions in Quick Start or getting started lessons. This closes #61
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/50ed85c9
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/50ed85c9
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/50ed85c9
Branch: refs/heads/master
Commit: 50ed85c999b842d0104d398b9802fb3fa627dcf4
Parents: 3419f58
Author: aditihilbert <ad...@runtime.io>
Authored: Sat Mar 19 00:00:35 2016 -0700
Committer: aditihilbert <ad...@runtime.io>
Committed: Sat Mar 19 00:00:35 2016 -0700
----------------------------------------------------------------------
docs/os/get_started/cross_tools.md | 13 +++++++++++--
docs/os/get_started/introduction.md | 2 ++
docs/os/get_started/native_tools.md | 22 ++++++++++++++++++++--
docs/os/get_started/project_create.md | 23 +++++++++++++----------
4 files changed, 46 insertions(+), 14 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/50ed85c9/docs/os/get_started/cross_tools.md
----------------------------------------------------------------------
diff --git a/docs/os/get_started/cross_tools.md b/docs/os/get_started/cross_tools.md
index e563e00..abf37cf 100644
--- a/docs/os/get_started/cross_tools.md
+++ b/docs/os/get_started/cross_tools.md
@@ -3,7 +3,9 @@
This page shows how to install tools to use some ARM based platforms with
Apache Mynewt.
-## Install ARM Cross tools for in Mac OS X
+<br>
+
+## Install ARM Cross tools in Mac OS X
### Install Tool Chain
@@ -30,6 +32,8 @@ available. Mynewt OS will eventually work with multiple versions available,
including the latest releases. However, at present we have tested only with
this version and recommend it for getting started.
+<br>
+
### Install OpenOCD
OpenOCD (Open On-Chip Debugger) is open-source software that allows your
@@ -47,7 +51,9 @@ $ ls -l $(which openocd)
lrwxr-xr-x 1 <user> admin 36 Sep 17 16:22 /usr/local/bin/openocd -> ../Cellar/open-ocd/0.8.0/bin/openocd
```
-## Install cross arm tools for Linux
+<br>
+
+## Install ARM cross arm tools for Linux
### Install Tool Chain
@@ -62,7 +68,10 @@ $ sudo apt-get update
$ sudo apt-get install gcc-arm-none-eabi
```
+<br>
+
###Install OpenOCD
+
OpenOCD (Open On-Chip Debugger) is open-source software that allows your
computer to interface with the JTAG debug connector on a variety of boards. A
JTAG connection lets you debug and test embedded target devices. For more on
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/50ed85c9/docs/os/get_started/introduction.md
----------------------------------------------------------------------
diff --git a/docs/os/get_started/introduction.md b/docs/os/get_started/introduction.md
index 4f5668c..09240e5 100644
--- a/docs/os/get_started/introduction.md
+++ b/docs/os/get_started/introduction.md
@@ -52,6 +52,8 @@ package management and build system tool, called *newt*.
You can install and build *newt* for [Linux](../../newt/install/newt_linux.md) or [Mac](../../newt/install/newt_mac.md).
+<br>
+
### Build your first Mynewt App with Newt ###
With the introductions out of the way, now is a good time to [get
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/50ed85c9/docs/os/get_started/native_tools.md
----------------------------------------------------------------------
diff --git a/docs/os/get_started/native_tools.md b/docs/os/get_started/native_tools.md
index 6626414..026aaff 100644
--- a/docs/os/get_started/native_tools.md
+++ b/docs/os/get_started/native_tools.md
@@ -6,6 +6,8 @@ you to run the test suites for all packages not requiring HW support.
This page provides guidance for MAC and Linux. See the relevant sections below.
+<br>
+
## Set up toolchain for Mac
### Install Brew
@@ -13,6 +15,8 @@ This page provides guidance for MAC and Linux. See the relevant sections below.
If you have not already installed Homebrew from the
[`newt` tutorials pages](../../newt/install/newt_mac.md), install it.
+<br>
+
###Install gcc/libc
OS X ships with a C compiler called Clang. To build applications for the Mynewt simulator, you will need a different compiler: gcc.
@@ -25,6 +29,8 @@ $ brew install gcc
🍺 /usr/local/Cellar/gcc/5.2.0: 1353 files, 248M
```
+<br>
+
###Install gdb
```no-highlight
@@ -35,21 +41,31 @@ $ brew install gdb
🍺 /usr/local/Cellar/gdb/7.10.1: XXX files,YYM
```
-*NOTE: When running a program with gdb, you may need to sign your gdb
+<br>
+
+**NOTE:** When running a program with gdb, you may need to sign your gdb
executable. [This page](https://gcc.gnu.org/onlinedocs/gnat_ugn/Codesigning-the-Debugger.html)
shows a recipe for gdb signing. Alternately you can skip this step and
continue without the ability to debug your mynewt application on your PC.*
+<br>
+
## Set up toolchain for Linux
The below procedure can be used to set up a Debian-based Linux system (e.g.,
Ubuntu). If you are running a different Linux distribution, you will need to
substitute invocations of _apt-get_ in the below steps with the package manager
that your distro uses.
+
+<br>
+
###Install gcc/libc that will produce 32-bit executables:
```no-highlight
$ sudo apt-get install gcc-multilib libc6-i386
-```
+```
+
+<br>
+
###Install gdb
```no-highlight
@@ -68,4 +84,6 @@ Setting up gdb (7.7.1-0ubuntu5~14.04.2) ...
```
+<br>
+
At this point you have installed all the necessary software to build and test code on a simluator for Linux. Proceed to the [Build test code on simulator](#build-test-code-on-simulator) section.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/50ed85c9/docs/os/get_started/project_create.md
----------------------------------------------------------------------
diff --git a/docs/os/get_started/project_create.md b/docs/os/get_started/project_create.md
index 9e671a2..bb3c838 100644
--- a/docs/os/get_started/project_create.md
+++ b/docs/os/get_started/project_create.md
@@ -2,6 +2,8 @@
This page shows how to create a Mynewt Project using the `newt` command-line tool.
+<br>
+
### Pre-Requisites
* Ensure you have installed [newt](../../newt/install/newt_mac.md) and that the
@@ -91,9 +93,7 @@ apache-mynewt-core
use the _-v_ (verbose) option to install.
-Once _newt install_ has successfully finished, the contents of _apache-mynewt-core_
-will have been downloaded into your local directory. You can view them by issuing the
-following commands in the base directory of the new project:
+Once _newt install_ has successfully finished, the contents of _apache-mynewt-core_ will have been downloaded into your local directory. You can view them by issuing the following commands in the base directory of the new project:
```no-highlight
$ tree -L 2 repos/apache-mynewt-core/
@@ -132,11 +132,11 @@ into your local directory!
<br>
-## Testing the project's packages
+### Test the project's packages
Use the following command to execute a package's unit tests:
-```no-highlight
+```
$ newt test <package-name>
```
@@ -155,11 +155,11 @@ All tests passed
<br>
-## Building the Project
+### Build the Project
To build and run your new application, simply issue the following command:
-```no-highlight
+```
$ newt build my_blinky_sim
Compiling base64.c
Compiling cbmem.c
@@ -178,9 +178,12 @@ Linking blinky.elf
App successfully built: /Users/sterling/dev/tmp/my_app/bin/my_blinky_sim/apps/blinky/blinky.elf
```
+<br>
+
You can run the simulated version of your project and see the simulated LED
-blink
-```no-highlight
+blink.
+
+```
./bin/my_blinky_sim/apps/blinky/blinky.elf
hal_gpio set pin 1 to 0
```
@@ -189,7 +192,7 @@ Just press _ctrl-c_ to exit.
<br>
-## Complete
+### Complete
Congratulations, you have created your first project! The blinky application
is not terribly exciting when it is run in the simulator, as there is no LED to
[2/7] incubator-mynewt-site git commit: Rework some of the Getting
Started pages.
Posted by ad...@apache.org.
Rework some of the Getting Started pages.
There was a lot of duplication among the Introduction and Creating Your
First Project pages. I merged the similar text into Creating Your First
Project, and removed it from the Introduction page.
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/9be2bd98
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/9be2bd98
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/9be2bd98
Branch: refs/heads/master
Commit: 9be2bd98bcc9d9ee1444bae1e391aadf5b4da218
Parents: df9b6fb
Author: Christopher Collins <cc...@apache.org>
Authored: Thu Mar 17 17:52:28 2016 -0700
Committer: Christopher Collins <cc...@apache.org>
Committed: Thu Mar 17 18:06:51 2016 -0700
----------------------------------------------------------------------
docs/os/get_started/cross_tools.md | 83 ++++++-----
docs/os/get_started/introduction.md | 141 +------------------
docs/os/get_started/native_tools.md | 35 ++---
docs/os/get_started/project_create.md | 216 ++++++++++++++++-------------
4 files changed, 198 insertions(+), 277 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/9be2bd98/docs/os/get_started/cross_tools.md
----------------------------------------------------------------------
diff --git a/docs/os/get_started/cross_tools.md b/docs/os/get_started/cross_tools.md
index 2cc9b8c..e563e00 100644
--- a/docs/os/get_started/cross_tools.md
+++ b/docs/os/get_started/cross_tools.md
@@ -1,57 +1,78 @@
# Installing Cross Tools for ARM
-This page shows how to install tools to use some ARM based platforms
-with mynewt.
+This page shows how to install tools to use some ARM based platforms with
+Apache Mynewt.
-## Install Cross tools for ARM MAC
+## Install ARM Cross tools for in Mac OS X
### Install Tool Chain
-Install the PX4 Toolchain and check the version installed. ARM maintains a pre-built GNU toolchain with a GCC source branch targeted at Embedded ARM Processors, namely Cortex-R/Cortex-M processor families. After installing, ensure that the symbolic link installed by Homebrew points to the correct version of the debugger. If not, you can either change the symbolic link using the "ln -f -s" command or just go ahead and try with the version it points to!
+Install the PX4 Toolchain and check the version installed. ARM maintains a
+pre-built GNU toolchain with a GCC source branch targeted at Embedded ARM
+Processors, namely Cortex-R/Cortex-M processor families. After installing,
+ensure that the symbolic link installed by Homebrew points to the correct
+version of the debugger.
+
```no-highlight
- $ brew tap PX4/homebrew-px4
- $ brew update
- $ brew install gcc-arm-none-eabi-49
- $ arm-none-eabi-gcc --version
- arm-none-eabi-gcc (GNU Tools for ARM Embedded Processors) 4.9.3 20150529 (release) [ARM/embedded-4_9-branch revision 224288]
- Copyright (C) 2014 Free Software Foundation, Inc.
- This is free software; see the source for copying conditions. There is NO
- warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- $ ls -al /usr/local/bin/arm-none-eabi-gdb
- lrwxr-xr-x 1 aditihilbert admin 69 Sep 22 17:16 /usr/local/bin/arm-none-eabi-gdb -> /usr/local/Cellar/gcc-arm-none-eabi-49/20150609/bin/arm-none-eabi-gdb
+$ brew tap PX4/homebrew-px4
+$ brew update
+$ brew install gcc-arm-none-eabi-49
+$ arm-none-eabi-gcc --version
+arm-none-eabi-gcc (GNU Tools for ARM Embedded Processors) 4.9.3 20150529 (release) [ARM/embedded-4_9-branch revision 224288]
+Copyright (C) 2014 Free Software Foundation, Inc.
+This is free software; see the source for copying conditions. There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+$ ls -al /usr/local/bin/arm-none-eabi-gdb
+lrwxr-xr-x 1 aditihilbert admin 69 Sep 22 17:16 /usr/local/bin/arm-none-eabi-gdb -> /usr/local/Cellar/gcc-arm-none-eabi-49/20150609/bin/arm-none-eabi-gdb
```
- Note: If no version is specified, brew will install the latest version available. Mynewt OS will eventually work with multiple versions available, including the latest releases. However, at present we have tested only with this version and recommend it for getting started.
+**Note:** If no version is specified, brew will install the latest version
+available. Mynewt OS will eventually work with multiple versions available,
+including the latest releases. However, at present we have tested only with
+this version and recommend it for getting started.
### Install OpenOCD
-Install OpenOCD (Open On-Chip Debugger), which is an open-source software that will allow you to interface with the JTAG debug connector/adaptor for the Olimex board, debug, and test embedded target devices, including the Olimex board. For more on OpenOCD go to [http://openocd.org](http://openocd.org).
+OpenOCD (Open On-Chip Debugger) is open-source software that allows your
+computer to interface with the JTAG debug connector on a variety of boards. A
+JTAG connection lets you debug and test embedded target devices. For more on
+OpenOCD go to [http://openocd.org](http://openocd.org).
+
+Currently, only OpenOCD 0.8.0 is supported.
+
```no-highlight
- $ brew install open-ocd
- $ which openocd
- /usr/local/bin/openocd
- $ ls -l $(which openocd)
- lrwxr-xr-x 1 <user> admin 36 Sep 17 16:22 /usr/local/bin/openocd -> ../Cellar/open-ocd/0.9.0/bin/openocd
+$ brew install open-ocd
+$ which openocd
+/usr/local/bin/openocd
+$ ls -l $(which openocd)
+lrwxr-xr-x 1 <user> admin 36 Sep 17 16:22 /usr/local/bin/openocd -> ../Cellar/open-ocd/0.8.0/bin/openocd
```
## Install cross arm tools for Linux
### Install Tool Chain
-For the LED project on the Olimex hardware, you should install gcc for AM 4.9.3. This package can be installed with apt-get as documented below. The steps are explained in depth at [https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded](https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded).
+On a Debian-based Linux distribution, gcc 4.9.3 for ARM can be installed with
+apt-get as documented below. The steps are explained in depth at
+[https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded](https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded).
+
```no-highlight
- $ sudo apt-get remove binutils-arm-none-eabi gcc-arm-none-eabi
- $ sudo add-apt-repository ppa:terry.guo/gcc-arm-embedded
- $ sudo apt-get update
- $ sudo apt-get install gcc-arm-none-eabi
+$ sudo apt-get remove binutils-arm-none-eabi gcc-arm-none-eabi
+$ sudo add-apt-repository ppa:terry.guo/gcc-arm-embedded
+$ sudo apt-get update
+$ sudo apt-get install gcc-arm-none-eabi
```
-
###Install OpenOCD
-And finally, install OpenOCD (Open On-Chip Debugger), which is an open-source software that will allow you to interface with the JTAG debug connector/adaptor for the Olimex board, debug your program and test embedded target devices which, including the Olimex board.
+OpenOCD (Open On-Chip Debugger) is open-source software that allows your
+computer to interface with the JTAG debug connector on a variety of boards. A
+JTAG connection lets you debug and test embedded target devices. For more on
+OpenOCD go to [http://openocd.org](http://openocd.org).
If you are running Ubuntu 15.x, then you are in luck and you can simply run:
```no-highlight
- $ sudo apt-get install openocd
+$ sudo apt-get install openocd
```
- For this project, you should download the openocd 0.8.0 package from [https://launchpad.net/ubuntu/vivid/+source/openocd](https://launchpad.net/ubuntu/vivid/+source/openocd). The direct link to the amd64 build is [http://launchpadlibrarian.net/188260097/openocd_0.8.0-4_amd64.deb](http://launchpadlibrarian.net/188260097/openocd_0.8.0-4_amd64.deb).
-
+ For this project, you should download the openocd 0.8.0 package from
+[https://launchpad.net/ubuntu/vivid/+source/openocd](https://launchpad.net/ubuntu/vivid/+source/openocd).
+The direct link to the amd64 build is
+[http://launchpadlibrarian.net/188260097/openocd_0.8.0-4_amd64.deb](http://launchpadlibrarian.net/188260097/openocd_0.8.0-4_amd64.deb).
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/9be2bd98/docs/os/get_started/introduction.md
----------------------------------------------------------------------
diff --git a/docs/os/get_started/introduction.md b/docs/os/get_started/introduction.md
index 2b3ac9c..76cf9b7 100644
--- a/docs/os/get_started/introduction.md
+++ b/docs/os/get_started/introduction.md
@@ -48,145 +48,12 @@ In order to provide all this functionality, and operate in an
extremely low resource environment, Mynewt provides a very fine-grained source
package management and build system tool, called *newt*.
-You can install and build *newt* for [Linux](http://mynewt.apache.org/newt/newt_linux/) or [Mac](http://mynewt.apache.org/newt/newt_mac/).
+You can install and build *newt* for Linux or
+[Mac](../../../newt/tutorials/newt_mac/)
### Build your first Mynewt App with Newt ###
-Before you start your first Mynewt application, you must first create a new Mynewt
-project with the *newt* tool:
-
-```no-highlight
-$ newt new my_project
-Downloading project skeleton from apache/incubator-mynewt-blinky...
-Installing skeleton in my_app...
-Project my_app successfully created.
-```
-
-Newt populates this new project with a base skeleton of a new Apache Mynewt
-project. It has the following structure:
-
-```no-highlight
-$ cd my_project
-$ tree -L 3
-.
-├── DISCLAIMER
-├── LICENSE
-├── NOTICE
-├── README.md
-├── apps
-│ └── blinky
-│ ├── pkg.yml
-│ └── src
-├── project.yml
-└── targets
- ├── my_blinky_sim
- │ ├── pkg.yml
- │ └── target.yml
- └── unittest
- ├── pkg.yml
- └── target.yml
-
-6 directories, 10 files
-$
-```
-
-Once you've switched into your new project's directory, the next step is to fetch
-any dependencies this project has. By default, all Newt projects rely on a single
-remote repository, apache-mynewt-core. Newt install will fetch this locally:
-
-```no-highlight
-$ newt install
-apache-mynewt-core
-$
-```
-
-*NOTE:* ```apache-mynewt-core``` may take a while to download, to see progress, use
-the ```-v``` (verbose) option to install.
-
-
-Once ```newt install``` has successfully finished, the contents of ```apache-mynewt-core```
-will have been downloaded into your local directory. You can view them by issuing the
-following commands in the base directory of the new project:
-
-```no-highlight
-$ cd repos/apache-mynewt-core
-$ tree -L2
-.
-<snip>
-├── fs
-│ ├── fs
-│ └── nffs
-├── hw
-│ ├── bsp
-│ ├── hal
-│ └── mcu
-├── libs
-│ ├── baselibc
-│ ├── bootutil
-│ ├── cmsis-core
-│ ├── console
-│ ├── elua
-│ ├── flash_test
-│ ├── imgmgr
-│ ├── json
-│ ├── mbedtls
-│ ├── newtmgr
-│ ├── os
-│ ├── shell
-│ ├── testreport
-│ ├── testutil
-│ └── util
-├── net
-│ └── nimble
-<snip>
-```
-
-As you can see, the core of the Apache Mynewt operating system has been brought
-into your local directory!
-
-New projects created with Newt, come with by default an example application
-(```apps/blinky```) and an example target (```my_blinky_sim```) which allows you to
-build that application for the simulated platform.
-
-With your new project, all you need to build and run your new application is to
-issue the following commands:
-
-```no-highlight
-$ newt build my_blinky_sim
-Compiling base64.c
-Compiling cbmem.c
-Compiling datetime.c
-Compiling tpq.c
-Archiving util.a
-Compiling main.c
-Archiving blinky.a
-Compiling flash_map.c
-Compiling hal_flash.c
-Archiving hal.a
-Compiling cons_fmt.c
-Compiling cons_tty.c
-<snip>
-Linking blinky.elf
-App successfully built: /Users/sterling/dev/tmp/my_app/bin/my_blinky_sim/apps/blinky/blinky.elf
-$ newt run my_blinky_sim
-(runs target my_blinky_sim on the simulator)
-```
-
-At this point you have your first Mynewt application!
-
-Apache Mynewt has a lot more functionality than just running simulated applications. It provides all
-the features you'll need to cross-compile your application, run it on real hardware and develop a
-full featured application.
-
-If you're interested in learning more, a good next step is to choose a project to
-[Get Started](http://mynewt.apache.org/os/get_started/project1/) with, and begin to familiarize
-yourself with operating within the newt environment. These projects will get your toolchain installed,
-and get you blinking an LED with the Apache Mynewt OS.
-
-After you've tried a few getting started projects, there are plenty of tutorials that will help
-expose you to much of the functionality provided by the Apache Mynewt Core Operating System. There is
-also full reference documentation for all of the Core Apache Mynewt APIs.
+With the introductions out of the way, now is a good time to [get
+started](project_create/) with your first Mynewt application.
Happy Hacking!
-
-
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/9be2bd98/docs/os/get_started/native_tools.md
----------------------------------------------------------------------
diff --git a/docs/os/get_started/native_tools.md b/docs/os/get_started/native_tools.md
index 184049c..2b2ef74 100644
--- a/docs/os/get_started/native_tools.md
+++ b/docs/os/get_started/native_tools.md
@@ -15,41 +15,45 @@ If you have not already installed Homebrew from the
###Install gcc/libc
-Use brew to install gcc.
+OS X ships with a C compiler called Clang. To build applications for the Mynewt simulator, you will need a different compiler: gcc.
```no-highlight
- $ brew install gcc
- ...
- ...
- ==> Summary
- 🍺 /usr/local/Cellar/gcc/5.2.0: 1353 files, 248M
+$ brew install gcc
+...
+...
+==> Summary
+🍺 /usr/local/Cellar/gcc/5.2.0: 1353 files, 248M
```
###Install gdb
```no-highlight
- $ brew install gdb
- ...
- ...
- ==> Summary
- 🍺 /usr/local/Cellar/gdb/7.10.1: XXX files,YYM
+$ brew install gdb
+...
+...
+==> Summary
+🍺 /usr/local/Cellar/gdb/7.10.1: XXX files,YYM
```
-_NOTE: When running a program with gdb, you may need to sign your gdb
+*NOTE: When running a program with gdb, you may need to sign your gdb
executable. [This page](https://gcc.gnu.org/onlinedocs/gnat_ugn/Codesigning-the-Debugger.html)
shows a recipe for gdb signing. Alternately you can skip this step and
-continue without the ability to debug your mynewt application on your PC._
+continue without the ability to debug your mynewt application on your PC.*
## Set up toolchain for Linux
+The below procedure can be used to set up a Debian-based Linux system (e.g.,
+Ubuntu). If you are running a different Linux distribution, you will need to
+substitute invocations of _apt-get_ in the below steps with the package manager
+that your distro uses.
###Install gcc/libc that will produce 32-bit executables:
```no-highlight
- $ sudo apt-get install gcc-multilib libc6-i386
+$ sudo apt-get install gcc-multilib libc6-i386
```
###Install gdb
```no-highlight
-$sudo apt-get install gdb
+$ sudo apt-get install gdb
Reading package lists... Done
Building dependency tree
@@ -61,7 +65,6 @@ The following NEW packages will be installed:
...
Processing triggers for man-db (2.6.7.1-1ubuntu1) ...
Setting up gdb (7.7.1-0ubuntu5~14.04.2) ...
-$
```
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/9be2bd98/docs/os/get_started/project_create.md
----------------------------------------------------------------------
diff --git a/docs/os/get_started/project_create.md b/docs/os/get_started/project_create.md
index bb46161..eeeb5b8 100644
--- a/docs/os/get_started/project_create.md
+++ b/docs/os/get_started/project_create.md
@@ -17,44 +17,48 @@ support native compiling to build the project this tutorial creates.
Choose a project name. For this tutorial we will call this project `myproj`.
Enter the `newt new myproj` command.
-```
- $ newt new myproj
- Downloading project skeleton from apache/incubator-mynewt-blinky...
- Installing skeleton in myproj...
- Project myproj successfully created.
+``` no-highlight
+$ newt new myproj
+Downloading project skeleton from apache/incubator-mynewt-blinky...
+Installing skeleton in myproj...
+Project myproj successfully created.
```
<br>
-The `newt` tool has created a project directory structure like the one below:
-
-```
- ─── myproj
- ├── DISCLAIMER
- ├── LICENSE
- ├── NOTICE
- ├── README.md
- ├── apps
- │ └── blinky
- │ ├── pkg.yml
- │ └── src
- │ └── main.c
- ├── project.yml
- └── targets
- ├── my_blinky_sim
- │ ├── pkg.yml
- │ └── target.yml
- └── unittest
- ├── pkg.yml
- └── target.yml
+Newt populates this new project with a base skeleton of a new Apache Mynewt
+project. It has the following structure:
+
+```no-highlight
+$ cd myproj
+$ tree -L 3
+.
+├── DISCLAIMER
+├── LICENSE
+├── NOTICE
+├── README.md
+├── apps
+│ └── blinky
+│ ├── pkg.yml
+│ └── src
+├── project.yml
+└── targets
+ ├── my_blinky_sim
+ │ ├── pkg.yml
+ │ └── target.yml
+ └── unittest
+ ├── pkg.yml
+ └── target.yml
+
+6 directories, 10 files
```
<br>
-`newt` has installed the base files for a project comprising the following.
+The Newt tool has installed the base files for a project comprising the following:
-1. file `project.yml` contains the repository list that the project uses to fetch
+1. the file `project.yml` contains the repository list that the project uses to fetch
its packages. Your project is a collection of repositories. In this case, the project just
comprises the core mynewt repository. Later you will add more repositories
to include other mynewt components.
@@ -63,7 +67,7 @@ and its package dependencies.
3. A target directory containing `my_blinky_sim`, a target descriptor used to
build a version of myproj. Use `newt target show` to see available build
targets.
-4. A non-build-able target called `unittest`. This is used
+4. A non-buildable target called `unittest`. This is used
internally by `newt` and is not a formal build target.
**NOTE:** the actual code and package files are not installed
@@ -73,96 +77,122 @@ internally by `newt` and is not a formal build target.
### Newt Install
-Change into the `myproj` directory. Then ask newt to install all the
-project package dependencies using `newt install`.
+Once you've switched into your new project's directory, the next step is to fetch
+any dependencies this project has. By default, all Newt projects rely on a
+single remote repository, apache-mynewt-core. The _newt install_ command will
+fetch this repository.
+```no-highlight
+$ newt install
+apache-mynewt-core
```
- $ newt install -v
- apache-mynewt-core
- Downloading repository description for apache-mynewt-core... success!
- Downloading repository incubator-mynewt-core (branch: master; commit: mynewt_0_8_0_b2_tag) at https://github.com/apache/incubator-mynewt-core.git
- Cloning into '/var/folders/7l/7b3w9m4n2mg3sqmgw2q1b9p80000gn/T/newt-repo969988348'...
- remote: Counting objects: 17935, done.
- remote: Compressing objects: 100% (234/234), done.
- remote: Total 17935 (delta 101), reused 0 (delta 0), pack-reused 17686
- Receiving objects: 100% (17935/17935), 6.18 MiB | 315.00 KiB/s, done.
- Resolving deltas: 100% (10541/10541), done.
- Checking connectivity... done.
- apache-mynewt-core successfully installed version 0.7.9-none
- $
-```
-Now you will have installed packages required to build your project. Note in
-the package you now have dependent packages stored in the `repos` directory
-under the specific repository you have included in the base project.
+**NOTE:** _apache-mynewt-core_ may take a while to download. To see progress,
+use the _-v_ (verbose) option to install.
+
+
+Once _newt install_ has successfully finished, the contents of _apache-mynewt-core_
+will have been downloaded into your local directory. You can view them by issuing the
+following commands in the base directory of the new project:
```no-highlight
- .
- ├── apps
- │ └── blinky
- │ └── src
- ├── repos
- │ └── apache-mynewt-core
- │ ├── apps
- │ ├── compiler
- │ ├── fs
- │ ├── hw
- │ ├── libs
- │ ├── net
- │ ├── scripts
- │ ├── sys
- │ └── targets
- └── targets
- ├── my_blinky_sim
- └── unittest
+$ tree -L 2 repos/apache-mynewt-core/
+.
+<snip>
+├── fs
+│ ├── fs
+│ └── nffs
+├── hw
+│ ├── bsp
+│ ├── hal
+│ └── mcu
+├── libs
+│ ├── baselibc
+│ ├── bootutil
+│ ├── cmsis-core
+│ ├── console
+│ ├── elua
+│ ├── flash_test
+│ ├── imgmgr
+│ ├── json
+│ ├── mbedtls
+│ ├── newtmgr
+│ ├── os
+│ ├── shell
+│ ├── testreport
+│ ├── testutil
+│ └── util
+├── net
+│ └── nimble
+<snip>
```
-Within each of these directories are the packages required to build your
-project for the various targets.
+As you can see, the core of the Apache Mynewt operating system has been brought
+into your local directory!
<br>
-## Testing the Project
+## Testing the project's packages
+
+Use the following command to execute a package's unit tests:
-To validate, you can also run all the units test through simulation.
+```no-highlight
+$ newt test <package-name>
+```
+
+To test all the packages in a project, specify `all` as the _<package-name\>_.
```no-highlight
- $ newt test all
- ...lots of compiling and testing...
- ...about 2 minutes later ...
- Archiving bootutil.a
- Linking test_bootutil
- Executing test: /myproj/bin/unittest/libs/bootutil/test_bootutil
- Passed tests: [net/nimble/host fs/nffs libs/os hw/hal libs/mbedtls libs/util sys/config libs/bootutil]
- All tests passed
+$ newt test all
+...lots of compiling and testing...
+...about 2 minutes later ...
+Archiving bootutil.a
+Linking test_bootutil
+Executing test: /myproj/bin/unittest/libs/bootutil/test_bootutil
+Passed tests: [net/nimble/host fs/nffs libs/os hw/hal libs/mbedtls libs/util sys/config libs/bootutil]
+All tests passed
```
<br>
## Building the Project
-To build the project you can use `newt build` using the target
+To build and run your new application, simply issue the following command:
```no-highlight
- $ newt build my_blinky_sim
- App successfully built: /bin/my_blinky_sim/apps/blinky/blinky.elf
+$ newt build my_blinky_sim
+Compiling base64.c
+Compiling cbmem.c
+Compiling datetime.c
+Compiling tpq.c
+Archiving util.a
+Compiling main.c
+Archiving blinky.a
+Compiling flash_map.c
+Compiling hal_flash.c
+Archiving hal.a
+Compiling cons_fmt.c
+Compiling cons_tty.c
+<snip>
+Linking blinky.elf
+App successfully built: /Users/sterling/dev/tmp/my_app/bin/my_blinky_sim/apps/blinky/blinky.elf
+$ newt run my_blinky_sim
+(runs target my_blinky_sim on the simulator)
```
+Just press _ctrl-c_ to exit.
<br>
-You can run the simulated version of your project and see the simulated LED
-blink
-```no-highlight
- ./bin/my_blinky_sim/apps/blinky/blinky.elf
- hal_gpio set pin 1 to 0
-```
-Just do `ctrl-c` to exit.
+## Complete
-<br>
+Congratulations, you have created your first project! The blinky application
+is not terribly exciting when it is run in the simulator, as there is no LED to
+blink. Apache Mynewt has a lot more functionality than just running simulated
+applications. It provides all the features you'll need to cross-compile your
+application, run it on real hardware and develop a full featured application.
-## Complete
+If you're interested in learning more, a good next step is to dig in to one of
+the tutorials and get a Mynewt project running on real hardware.
-Congratulations, you have created your first project! This project contains
-the core OS, a simple application to blink an LED and all of the dependencies
-required.
+Happy Hacking!
[3/7] incubator-mynewt-site git commit: Re-add native GPIO output;
tutorials link.
Posted by ad...@apache.org.
Re-add native GPIO output; tutorials link.
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/561cb783
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/561cb783
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/561cb783
Branch: refs/heads/master
Commit: 561cb783b1b1d5eaf9cd7890a79844a75bdec7ff
Parents: 146a7b9
Author: Christopher Collins <cc...@apache.org>
Authored: Fri Mar 18 13:54:57 2016 -0700
Committer: Christopher Collins <cc...@apache.org>
Committed: Fri Mar 18 13:55:41 2016 -0700
----------------------------------------------------------------------
docs/os/get_started/project_create.md | 13 +++++++++----
1 file changed, 9 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/561cb783/docs/os/get_started/project_create.md
----------------------------------------------------------------------
diff --git a/docs/os/get_started/project_create.md b/docs/os/get_started/project_create.md
index eeeb5b8..cbe607a 100644
--- a/docs/os/get_started/project_create.md
+++ b/docs/os/get_started/project_create.md
@@ -176,14 +176,19 @@ Compiling cons_tty.c
<snip>
Linking blinky.elf
App successfully built: /Users/sterling/dev/tmp/my_app/bin/my_blinky_sim/apps/blinky/blinky.elf
-$ newt run my_blinky_sim
-(runs target my_blinky_sim on the simulator)
```
+
+You can run the simulated version of your project and see the simulated LED
+blink
+```no-highlight
+./bin/my_blinky_sim/apps/blinky/blinky.elf
+hal_gpio set pin 1 to 0
+```
+
Just press _ctrl-c_ to exit.
<br>
-
## Complete
Congratulations, you have created your first project! The blinky application
@@ -193,6 +198,6 @@ applications. It provides all the features you'll need to cross-compile your
application, run it on real hardware and develop a full featured application.
If you're interested in learning more, a good next step is to dig in to one of
-the tutorials and get a Mynewt project running on real hardware.
+the [tutorials](../tutorials/tutorials) and get a Mynewt project running on real hardware.
Happy Hacking!
[6/7] incubator-mynewt-site git commit: Merge branch 'apache-master'
Posted by ad...@apache.org.
Merge branch 'apache-master'
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/3419f586
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/3419f586
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/3419f586
Branch: refs/heads/master
Commit: 3419f5862b2558a36cd567dcfd0da9571de9485c
Parents: 561cb78 dcf6bf0
Author: Christopher Collins <cc...@apache.org>
Authored: Fri Mar 18 17:35:35 2016 -0700
Committer: Christopher Collins <cc...@apache.org>
Committed: Fri Mar 18 17:35:35 2016 -0700
----------------------------------------------------------------------
custom-theme/base.html | 3 +
custom-theme/next_prev_links.html | 13 +
docs/newt/install/newt_linux.md | 135 +++++++++++
docs/newt/install/newt_mac.md | 141 +++++++++++
docs/newt/tutorials/newt_mac.md | 124 ----------
docs/newtmgr/project-slinky.md | 2 +-
docs/newtmgr/project-target-slinky.md | 2 +-
docs/os/get_started/get_started.md | 6 +-
docs/os/get_started/introduction.md | 5 +-
docs/os/get_started/native_tools.md | 2 +-
docs/os/get_started/project_create.md | 2 +-
docs/os/tutorials/arduino_zero.md | 2 +-
docs/os/tutorials/event_queue.md | 367 +++++++++++++++++++++++++++++
mkdocs.yml | 7 +-
14 files changed, 675 insertions(+), 136 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/3419f586/docs/os/get_started/introduction.md
----------------------------------------------------------------------
diff --cc docs/os/get_started/introduction.md
index 76cf9b7,a617ecc..4f5668c
--- a/docs/os/get_started/introduction.md
+++ b/docs/os/get_started/introduction.md
@@@ -48,12 -50,152 +50,11 @@@ In order to provide all this functional
extremely low resource environment, Mynewt provides a very fine-grained source
package management and build system tool, called *newt*.
- You can install and build *newt* for Linux or
- [Mac](../../../newt/tutorials/newt_mac/)
+ You can install and build *newt* for [Linux](../../newt/install/newt_linux.md) or [Mac](../../newt/install/newt_mac.md).
-<br>
-
### Build your first Mynewt App with Newt ###
-Before you start your first Mynewt application, you must first create a new Mynewt
-project with the *newt* tool:
-
-```no-highlight
-$ newt new my_project
-Downloading project skeleton from apache/incubator-mynewt-blinky...
-Installing skeleton in my_app...
-Project my_app successfully created.
-```
-
-<br>
-
-Newt populates this new project with a base skeleton of a new Apache Mynewt
-project. It has the following structure:
-
-```no-highlight
-$ cd my_project
-$ tree -L 3
-.
-├── DISCLAIMER
-├── LICENSE
-├── NOTICE
-├── README.md
-├── apps
-│ └── blinky
-│ ├── pkg.yml
-│ └── src
-├── project.yml
-└── targets
- ├── my_blinky_sim
- │ ├── pkg.yml
- │ └── target.yml
- └── unittest
- ├── pkg.yml
- └── target.yml
-
-6 directories, 10 files
-$
-```
-
-Once you've switched into your new project's directory, the next step is to fetch
-any dependencies this project has. By default, all Newt projects rely on a single
-remote repository, apache-mynewt-core. Newt install will fetch this locally:
-
-```no-highlight
-$ newt install
-apache-mynewt-core
-$
-```
-
-**NOTE:** ```apache-mynewt-core``` may take a while to download, to see progress, use the ```-v``` (verbose) option to install.
-
-
-Once ```newt install``` has successfully finished, the contents of ```apache-mynewt-core```
-will have been downloaded into your local directory. You can view them by issuing the
-following commands in the base directory of the new project:
-
-```no-highlight
-$ cd repos/apache-mynewt-core
-$ tree -L2
-.
-<snip>
-├── fs
-│ ├── fs
-│ └── nffs
-├── hw
-│ ├── bsp
-│ ├── hal
-│ └── mcu
-├── libs
-│ ├── baselibc
-│ ├── bootutil
-│ ├── cmsis-core
-│ ├── console
-│ ├── elua
-│ ├── flash_test
-│ ├── imgmgr
-│ ├── json
-│ ├── mbedtls
-│ ├── newtmgr
-│ ├── os
-│ ├── shell
-│ ├── testreport
-│ ├── testutil
-│ └── util
-├── net
-│ └── nimble
-<snip>
-```
-
-<br>
-
-As you can see, the core of the Apache Mynewt operating system has been brought
-into your local directory!
-
-New projects created with Newt, come with by default an example application
-(```apps/blinky```) and an example target (```my_blinky_sim```) which allows you to
-build that application for the simulated platform.
-
-With your new project, all you need to build and run your new application is to
-issue the following commands:
-
-```no-highlight
-$ newt build my_blinky_sim
-Compiling base64.c
-Compiling cbmem.c
-Compiling datetime.c
-Compiling tpq.c
-Archiving util.a
-Compiling main.c
-Archiving blinky.a
-Compiling flash_map.c
-Compiling hal_flash.c
-Archiving hal.a
-Compiling cons_fmt.c
-Compiling cons_tty.c
-<snip>
-Linking blinky.elf
-App successfully built: /Users/sterling/dev/tmp/my_app/bin/my_blinky_sim/apps/blinky/blinky.elf
-$ newt run my_blinky_sim
-(runs target my_blinky_sim on the simulator)
-```
-
-<br>
-
-At this point you have your first Mynewt application!
-
-Apache Mynewt has a lot more functionality than just running simulated applications. It provides all
-the features you'll need to cross-compile your application, run it on real hardware and develop a
-full featured application.
-
-If you're interested in learning more, a good next step is to choose a project to
-[get started](get_started.md) with, and begin to familiarize
-yourself with operating within the newt environment. These projects will get your toolchain installed,
-and get you blinking an LED with the Apache Mynewt OS.
-
-After you've tried a few getting started projects, there are plenty of tutorials that will help
-expose you to much of the functionality provided by the Apache Mynewt Core Operating System. There is
-also full reference documentation for all of the Core Apache Mynewt APIs.
+With the introductions out of the way, now is a good time to [get
+started](project_create/) with your first Mynewt application.
Happy Hacking!
-
-
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/3419f586/docs/os/get_started/native_tools.md
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/3419f586/docs/os/get_started/project_create.md
----------------------------------------------------------------------
[5/7] incubator-mynewt-site git commit: add a file describing a
repository
Posted by ad...@apache.org.
add a file describing a repository
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/8a387844
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/8a387844
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/8a387844
Branch: refs/heads/master
Commit: 8a387844bc6618133cc91fbbf60dd80207e7a486
Parents: 06b2c1c
Author: Paul Dietrich <pa...@yahoo.com>
Authored: Thu Mar 17 16:28:53 2016 -0700
Committer: Christopher Collins <cc...@apache.org>
Committed: Fri Mar 18 13:55:41 2016 -0700
----------------------------------------------------------------------
docs/os/tutorials/add_repos.md | 283 ++++++++++++++++++++++++++++++++++++
mkdocs.yml | 1 +
2 files changed, 284 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/8a387844/docs/os/tutorials/add_repos.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/add_repos.md b/docs/os/tutorials/add_repos.md
new file mode 100644
index 0000000..39c7a4e
--- /dev/null
+++ b/docs/os/tutorials/add_repos.md
@@ -0,0 +1,283 @@
+## What is a Repository
+
+A repository is a version-ed mynewt project, which is a
+collection of mynewt packages organized in a specific
+way.
+
+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 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.
+
+# Additional Repos
+
+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 candidate to be held in
+different repos.
+* **Software licensing**. Some software has 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`.
+
+## 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
+```
+
+View the `project.yml` section and you will see a line describing the repos:
+
+```no-highlight
+project.repositories:
+ - apache-mynewt-core
+```
+
+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.
+
+```no-highlight
+project.repositories:
+ - apache-mynewt-core
+ - another_repo_named_x
+```
+
+## 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`.
+
+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 version 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 user name 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.
+
+## 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 if 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
+```
+
+## What Version of the Repo
+
+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 below for a description of the version system.
+
+## What is in a Repo
+
+A repo is a collection of mynewt packages organized in a specific
+way and stored in one of the supported code storage methods described above.
+
+A repo is a mynewt project, with an additional file `repository.yml`
+which describes the repo for `newt` (and humans browsing them).
+
+There is one key consideration for this `repository.yml` file. The
+`repository.yml` file only lives 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 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"
+```
+
+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.
+
+## Repo Version
+
+The version field argument in your `project.yml` file 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>
+```
+
+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 number version, e.g.
+
+```no-highlight
+1.2.8-stable
+```
+
+A `repository.yml` file contains information to match this version request
+into a git branch to fetch for your project.
+
+Its up to the repository maintainer to map these to branches of the
+repository. For example, 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` its resolved to version
+`1.2.0` (perhaps `1.2.1` is not stable yet), which resolves to a specific
+branch `xxx_branch_1_2_0`. This is the branch that `newt` fetches into
+your project.
+
+## How do I 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, its not a mynewt repository can cant be included in your
+project via the mynewt 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.
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/8a387844/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index 5e7faa3..6479529 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -28,6 +28,7 @@ pages:
- 'Write a Test Suite for a Package': 'os/tutorials/unit_test.md'
- 'Air-quality Sensor project': 'os/tutorials/air_quality_sensor.md'
- 'Edit Docs': 'os/tutorials/how_to_edit_docs.md'
+ - 'Additional Repositories': 'os/tutorials/add_repos.md'
- OS User Guide:
- toc: 'os/os_user_guide.md'
- OS Core:
[4/7] incubator-mynewt-site git commit: Minor edits to the Additional
REpositories tutorial mainly for formatting. This closes #59.
Posted by ad...@apache.org.
Minor edits to the Additional REpositories tutorial mainly for formatting. This closes #59.
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/146a7b9f
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/146a7b9f
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/146a7b9f
Branch: refs/heads/master
Commit: 146a7b9f42bc451ca474f8c360a409ba30411476
Parents: 8a38784
Author: aditihilbert <ad...@runtime.io>
Authored: Fri Mar 18 10:06:02 2016 -0700
Committer: Christopher Collins <cc...@apache.org>
Committed: Fri Mar 18 13:55:41 2016 -0700
----------------------------------------------------------------------
docs/os/tutorials/add_repos.md | 130 ++++++++++++++++++++++--------------
1 file changed, 79 insertions(+), 51 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/146a7b9f/docs/os/tutorials/add_repos.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/add_repos.md b/docs/os/tutorials/add_repos.md
index 39c7a4e..6213c41 100644
--- a/docs/os/tutorials/add_repos.md
+++ b/docs/os/tutorials/add_repos.md
@@ -1,39 +1,40 @@
-## What is a Repository
+## Additional Repositories
-A repository is a version-ed mynewt project, which is a
-collection of mynewt packages organized in a specific
+### What is a Repository
+
+A repository is a version-ed Mynewt project, which is a
+collection of Mynewt packages organized in a specific
way.
-What differentiates a repository from a mynewt project is the presence of a
+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 the remainder of this document we'll use the term repo as shorthand for a
-mynewt repository.
+below. **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
+to share Mynewt packages and projects. In fact, the Mynewt-core is
distributed as a repo.
-# Additional Repos
+<br>
-Why does mynewt need additional repos?
+### Why does Mynewt need additional repos?
-Repos add functionality
-not included in the mynewt core. New repos might be created for
+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.
+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 candidate to be held in
+are not core to all Mynewt users. These are likely candidates to be held in
different repos.
-* **Software licensing**. Some software has licenses that make them incompatible
+* **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`.
+valuable components to some Mynewt users, but cannot be contained in the `apache-Mynewt-core`.
+
+<br>
-## What Repos are in my Project
+### 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:
@@ -45,26 +46,32 @@ $ 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
+ - apache-Mynewt-core
```
+<br>
+
By default, this newly created project uses a single repo called
-`apache-mynewt-core`.
+`apache-Mynewt-core`.
If you wish to add additional repos, you would add
additional lines to the `project.repositories` variable like this.
```no-highlight
project.repositories:
- - apache-mynewt-core
+ - apache-Mynewt-core
- another_repo_named_x
```
-## Repo Descriptors
+<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`
@@ -73,7 +80,7 @@ information on obtaining the repo.
In the same `myproj` above you will see the following repo descriptor.
```no-highlight
-repository.apache-mynewt-core:
+repository.apache-Mynewt-core:
type: github
vers: 0-latest
user: apache
@@ -81,7 +88,9 @@ repository.apache-mynewt-core:
```
A repo descriptor starts with `repository.<name>.`. In this example, the
-descriptor specifies the information for the `apache-mynewt-core`.
+descriptor specifies the information for the `apache-Mynewt-core`.
+
+<br>
The fields within the descriptor have the following definitions:
@@ -90,7 +99,7 @@ of `newt` only supports github. Future versions may support generic git or othe
code storage mechanisms.
* **vers** -- The version of the repo to use for your project. A source
-code repository contains many version of the source. This field is used to
+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.
@@ -99,14 +108,16 @@ 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 user name described above. Consider the repository
+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.
-## Adding Existing Repos to my Project
+<br>
+
+### Adding Existing Repos to my Project
To add a new repo to your project, you have to complete two steps.
@@ -122,33 +133,35 @@ An example if a `project.yml` file with two repositories is shown below:
project.name: "my_project"
project.repositories:
- - apache-mynewt-core
- - mynewt_arduino_zero
-
+ - 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:
+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:
+repository.Mynewt_arduino_zero:
type: github
vers: 0-latest
user: runtimeinc
- repo: mynewt_arduino_zero
+ repo: Mynewt_arduino_zero
```
-## What Version of the Repo
+<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
+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.
```
@@ -157,13 +170,15 @@ please use `0-latest` in the `vers` field in your repo descriptor.
See below for a description of the version system.
-## What is in a Repo
+<br>
+
+### What is in a Repo
-A repo is a collection of mynewt packages organized in a specific
+A repo is a collection of Mynewt packages organized in a specific
way and stored in one of the supported code storage methods described above.
-A repo is a mynewt project, with an additional file `repository.yml`
-which describes the repo for `newt` (and humans browsing them).
+A repo is a Mynewt project with an additional file `repository.yml`
+which describes the repo for use by `newt` (and humans browsing them).
There is one key consideration for this `repository.yml` file. The
`repository.yml` file only lives in the master branch of the git
@@ -172,17 +187,19 @@ 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 the apache-mynewt-core
+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.7.9": "Mynewt_0_8_0_b2_tag"
"0-latest": "0.7.9"
"0.8-latest": "0.7.9"
```
-it contains the following:
+<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.
@@ -190,7 +207,9 @@ your `project.yml` file. This is the name you in include in the `project.repos
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.
-## Repo Version
+<br>
+
+### Repo Version
The version field argument in your `project.yml` file has the following format:
@@ -210,6 +229,8 @@ or
<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
@@ -224,17 +245,19 @@ the version number and stability value. For example:
* `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 number version, e.g.
+You cannot specify a stability string with a fully numbered version, e.g.
```no-highlight
1.2.8-stable
```
+<br>
+
A `repository.yml` file contains information to match this version request
into a git branch to fetch for your project.
Its up to the repository maintainer to map these to branches of the
-repository. For example, in a fictitious repository, the following are
+repository. For example, let's say in a fictitious repository the following are
defined.
```no-highlight
@@ -259,21 +282,26 @@ When the `project.yml` file asks for `1.2-stable` its resolved to version
branch `xxx_branch_1_2_0`. This is the branch that `newt` fetches into
your project.
-## How do I find out what Repos are available for Mynewt components
+<br>
+
+### How to find out what Repos are available for Mynewt components
-Currently, there is no `newt` command to locate/search mynewt package
+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
+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, its not a mynewt repository can cant be included in your
-project via the mynewt tool.
+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>
+
+