Added STM32F4DISCOVERY to the list of supported boards
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/32902442 Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/32902442 Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/32902442 Branch: refs/heads/master Commit: 32902442dadad4f49cdad50c50bcb4227757b682 Parents: 2f682cd Author: aditihilbert <[email protected]> Authored: Fri Nov 11 17:00:42 2016 -0800 Committer: aditihilbert <[email protected]> Committed: Fri Nov 11 17:00:42 2016 -0800 ---------------------------------------------------------------------- custom-theme/landing.html | 3 + docs/about.md | 3 +- docs/index.md | 2 +- docs/network/ble/bletiny/bletiny_GAP.md | 128 +++-------- docs/network/ble/bletiny/bletiny_GATT.md | 56 ++--- docs/network/ble/bletiny/bletiny_advdata.md | 28 +-- docs/network/ble/bletiny_api.md | 144 +++++++++++++ docs/network/ble/ini_stack/ble_parent_ini.md | 2 +- docs/newt/install/newt_linux.md | 23 -- docs/newt/install/newt_mac.md | 25 --- docs/newt/newt_intro.md | 11 - docs/os/core_os/porting/port_bsp.md | 20 +- docs/os/core_os/porting/port_os.md | 41 ++-- docs/os/core_os/time/os_time_tick.md | 8 +- docs/os/introduction.md | 32 +-- .../os/modules/hal/hal_cputime/hal_cpu_timer.md | 14 +- docs/os/modules/hal/hal_gpio/hal_gpio.md | 19 +- docs/os/modules/split/split.md | 173 ++++++++++----- docs/os/tutorials/arduino_zero.md | 98 ++++----- docs/os/tutorials/bleprph/bleprph-adv.md | 114 +++++----- docs/os/tutorials/bleprph/bleprph-app.md | 108 ++++++++++ docs/os/tutorials/bleprph/bleprph-chr-access.md | 212 +++++++++++-------- docs/os/tutorials/bleprph/bleprph-conn.md | 156 ++++++++++++++ docs/os/tutorials/bleprph/bleprph-intro.md | 5 +- docs/os/tutorials/bleprph/bleprph-svc-reg.md | 128 +++++------ docs/os/tutorials/blinky_sram_olimex.md | 41 ++-- docs/os/tutorials/ibeacon.md | 2 +- docs/os/tutorials/olimex.md | 56 ++--- docs/os/tutorials/pics/LightBlue-1.jpg | Bin 0 -> 90014 bytes docs/os/tutorials/pics/LightBlue-2.jpg | Bin 0 -> 121238 bytes docs/os/tutorials/pics/LightBlue-3.jpg | Bin 0 -> 122447 bytes docs/os/tutorials/pics/LightBlue-4.jpg | Bin 0 -> 94431 bytes docs/os/tutorials/pics/LightBlue-5.jpg | Bin 0 -> 53663 bytes docs/os/tutorials/pics/LightBlue-6.jpg | Bin 0 -> 97461 bytes docs/os/tutorials/project-slinky.md | 8 +- docs/os/tutorials/project-target-slinky.md | 46 ++-- docs/os/tutorials/tutorials.md | 24 +-- docs/quick-start.md | 2 +- mkdocs.yml | 146 +------------ 39 files changed, 1054 insertions(+), 824 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/custom-theme/landing.html ---------------------------------------------------------------------- diff --git a/custom-theme/landing.html b/custom-theme/landing.html index d0014e5..2473b84 100644 --- a/custom-theme/landing.html +++ b/custom-theme/landing.html @@ -127,6 +127,9 @@ <a href="http://www.st.com/en/evaluation-tools/stm32f3discovery.html";> STM32F3DISCOVERY </a> from ST Micro (Cortex-M4) </li> <li> + <a href="http://www.st.com/en/evaluation-tools/stm32f4discovery.html";> STM32F4DISCOVERY </a> from ST Micro (Cortex-M4) + </li> + <li> <a href=" https://www.olimex.com/Products/ARM/ST/STM32-E407/open-source-hardware";> STM32-E407 </a> from Olimex (Cortex-M4) </li> <li> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/about.md ---------------------------------------------------------------------- diff --git a/docs/about.md b/docs/about.md index 5ba9e00..a842db4 100644 --- a/docs/about.md +++ b/docs/about.md @@ -7,7 +7,6 @@ Some upcoming features: * HAL redesign to abstract across a diverse set of chip peripherals ([View discussion thread](http://mail-archives.apache.org/mod_mbox/incubator-mynewt-dev/201606.mbox/%3C06CB0682-8F67-4C3F-93E4-6A20444487A1%40apache.org%3E)) * HAL for SPI access (master and slave) * Ability for drivers to turn on/off low power settings automatically -* Support for Wi-Fi controllers via a socket interface <font color="#F2853F"> The detailed roadmap is tracked on [JIRA for Mynewt](https://issues.apache.org/jira/browse/MYNEWT/?selectedTab=com.atlassian.jira.jira-projects-plugin:roadmap-panel). </font> @@ -18,7 +17,7 @@ Some upcoming features: The WISHLIST at the top of the roadmap on [JIRA for Mynewt](https://issues.apache.org/jira/browse/MYNEWT/?selectedTab=com.atlassian.jira.jira-projects-plugin:roadmap-panel) features all the new ideas awaiting discussion and review. Once the community decides to go ahead with a request, it is scheduled into a release. Generally, effort is made to schedule a requested feature into a particular version no later than 6 weeks prior to the planned release date. -If you have suggestions for a new feature, use case, or implementation improvements, file a JIRA ticket with Issue Type set to "Wish". Introduce it in the [dev@](http://mail-archives.apache.org/mod_mbox/incubator-mynewt-dev/) mailing list with a link to the JIRA ticket. This assumes you have signed up for an account on JIRA and submitted a request to the dev@ mailing list for your JIRA username to be added to the Apache Mynewt (MYNEWT) project. +If you have suggestions for a new feature, use case, or implementation improvements, file a JIRA ticket with Issue Type set to "Wish". Introduce it in the [dev@]([email protected]) mailing list with a link to the JIRA ticket. This assumes you have signed up for an account on JIRA and submitted a request to the dev@ mailing list for your JIRA username to be added to the Apache Mynewt (MYNEWT) project. <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/index.md ---------------------------------------------------------------------- diff --git a/docs/index.md b/docs/index.md index 8daa8aa..bc1906c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1 +1 @@ -[//]: # (This is not used - see landing.html for content) +Apache Mynewt is a real-time, modular operating system for connected IoT devices that need to operate for long periods of time under power, memory, and storage constraints. The first connectivity stack offered is BLE 4.2. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/network/ble/bletiny/bletiny_GAP.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/bletiny/bletiny_GAP.md b/docs/network/ble/bletiny/bletiny_GAP.md index a6ff368..f89664c 100644 --- a/docs/network/ble/bletiny/bletiny_GAP.md +++ b/docs/network/ble/bletiny/bletiny_GAP.md @@ -5,107 +5,47 @@ Generic Access Profile (GAP) defines the generic procedures related to discovery of Bluetooth devices (idle mode procedures) and link management aspects of connecting to Bluetooth devices (connecting mode procedures). It also defines procedures related to use of different security levels. -Several different modes and procedures may be performed simultaneously over an LE physical transport. The following modes and procedures are defined for use over an LE physical transport: - -1. **Broadcast mode and observation procedure** - - These allow two devices to communicate in a unidirectional connectionless manner using the advertising events. -2. **Discovery modes and procedures** +Several different modes and procedures may be performed simultaneously over an LE physical transport. The following modes and procedures are defined for use over an LE physical transport:1. **Broadcast mode and observation procedure** + - These allow two devices to communicate in a unidirectional connectionless manner using the advertising events.2. **Discovery modes and procedures** - All devices shall be in either non-discoverable mode or one of the discoverable modes. - A device in the discoverable mode shall be in either the general discoverable mode or the limited discoverable mode. - - A device in non-discoverable mode will not be discovered by any device that is performing either the general discovery procedure or the limited discovery procedure. -3. **Connection modes and procedures** + - A device in non-discoverable mode will not be discovered by any device that is performing either the general discovery procedure or the limited discovery procedure.3. **Connection modes and procedures** - allow a device to establish a connection to another device. - allow updating of parameters of the connection - - allow termination of the connection -4. **Bonding modes and procedures** + - allow termination of the connection 4. **Bonding modes and procedures** - Bonding allows two connected devices to exchange and store security and identity information to create a trusted relationship. - - Bonding can occur only between two devices in bondable mode. - - -<br> - - -###Usage API - - -|**Item No.** | **Modes and Procedures** | **nimBLE command** | -|----|---------|---------------| -| 1 | Broadcast Mode | `b adv conn=non disc=x` | -| | Observation Procedure | `b scan dur=x disc=x type=x filt=x` | -| 2 | Non-Discoverable mode | `b adv conn=x disc=non` | -| | Limited Discoverable mode | `b adv conn=x disc=ltd` | -| | General Discoverable mode | `b adv conn=x disc=gen` | -| | Limited Discovery procedure | `b scan dur=x disc=ltd type=active filt=no_wl` | -| | General Discovery procedure | `b scan dur=x disc=gen type=active filt=no_wl` | -| | Name Discovery procedure | `b scan dur=x` <br> `b scan cancel` <br> `b conn peer_addr_type=x peer_addr=x` <br> `b read uuid=0x2a00` | + - Bonding can occur only between two devices in bondable mode.<br> +###Usage API +|**Item No.** | **Modes and Procedures** | **nimBLE command** ||----|---------|---------------| +| 1 | Broadcast Mode | `b adv conn=non disc=x` || | Observation Procedure | `b scan dur=x disc=x type=x filt=x` | +| 2 | Non-Discoverable mode | `b adv conn=x disc=non` || | Limited Discoverable mode | `b adv conn=x disc=ltd` | +| | General Discoverable mode | `b adv conn=x disc=gen` || | Limited Discovery procedure | `b scan dur=x disc=ltd type=active filt=no_wl` | +| | General Discovery procedure | `b scan dur=x disc=gen type=active filt=no_wl` | +| | Name Discovery procedure | UNSUPPORTED | | 3 | Non-connectable mode | `b adv conn=non disc=x` | -| | Directed connectable mode | `b adv conn=dir [own_addr_type=x] [disc=x] [dur=x]` | -| | Undirected connectable mode | `b adv conn=und [own_addr_type=x] [disc=x] [dur=x]` | -| | Auto connection establishment procedure | `b wl addr_type=x addr=x [addr_type=y addr=y] [...]` <br> `b conn addr_type=wl` | -| | General connection establishment procedure | `b scan dur=x` <br> `b scan cancel` <br> `b conn peer_addr_type=x peer_addr=x` | -| | Selective connection establishment procedure | `b wl addr_type=x addr=x [addr_type=y addr=y] [...]` <br> `b scan filt=use_wl dur=x` <br> `b scan cancel` <br> `b conn peer_addr_type=x peer_addr=x [own_addr_type=x]` | -| | Direct connection establishment procedure | `b conn addr_type=x addr=x [params]` | -| | Connection parameter update procedure | `b update conn=x <params>` | -| | Terminate connection procedure | `b term conn=x` | -| 4 | Non-Bondable mode | `b set sm_data bonding=0` [\*] | -| | Bondable mode | `b set sm_data bonding=1` [\*] | -| | Bonding procedure | `b sec start conn=x` [\*] | - -**[\*]** Security is disabled by default in bletiny. To use the bonding modes and procedures, add the `-DNIMBLE_OPT_SM=1` cflag to your target. - -<br> - -### Address Types - -| *bletiny string* | *Description* | *Notes* | -|------------------|---------------| -| public | Public address. | | -| random | Random static address. | | -| rpa_pub | Resolvable private address, public identity. | Not available for all commands. | -| rpa_rnd | Resolvable private address, random static identity. | Not available for all commands. | -| wl | Use white list; ignore peer_addr parameter. | Only availble for "conn" command. | - -### Connection Parameters - -The Connection parameter definitions can be found in Section 7.8.12 of the BLUETOOTH SPECIFICATION Version 4.2 [Vol 2, Part E]. - -| *Name* | *Description* | *bletiny string* | -|----|---------|---------------| -| LE_Scan_Interval | Recommendation from the Host on how long the Controller should scan | scan_itvl | -| LE_Scan_Window | Recommendation from the Host on how frequently the Controller should scan | scan_window | -| Peer_Address_Type | Whether the peer is using a public or random address (see Address types table). | peer_addr_type | -| Peer_Address | The 6-byte device address of the peer; ignored if white list is used | peer_addr | -| Own_Address_Type | The type of address to use when initiating the connection (see Address types table) | own_addr_type | -| Conn_Interval_Min | Defines minimum allowed connection interval | itvl_min | -| Conn_Interval_Max | Defines maximum allowed connection interval | itvl_max | +| | Directed connectable mode | `b adv conn=dir disc=x addr_type=x addr=x` | +| | Undirected connectable mode | `b adv conn=und disc=x` | +| | Auto connection establishment procedure | `b wl addr_type=x addr=x` | +| | Auto connection establishment procedure | `b conn addr_type=wl` | +| | General connection establishment procedure | AVAILABLE SOON | +| | Selective connection establishment procedure | AVAILABLE SOON | +| | Direct connection establishment procedure | `b conn addr_type=x addr=x [params]` | +| | Connection parameter update procedure | `b update conn=x <params>` | +| | Terminate connection procedure | `b term conn=x` | +| 4 | Non-Bondable mode | AVAILABLE SOON | +| | Bondable mode | AVAILABLE SOON | +| | Bonding procedure | AVAILABLE SOON |<br> +### Connection Parameters + +The Connection parameter definitions can be found in Section 7.8.12 of the BLUETOOTH SPECIFICATION Version 4.2 [Vol 2, Part E].|**Name** | **Description** | **nimBLE parameter** ||----|---------|---------------| +| Minimum connection interval | Defines minimum allowed connection interval| itvl_min | +| Maximum connection interval | Defines maximum allowed connection interval | itvl_max | | Conn_Latency | Defines the maximum allowed connection latency | latency | | Supervision_Timeout | Link supervision timeout for the connection. | timeout | -| Minimum_CE_Length | Informative parameter providing the Controller with the expected minimum length of the connection event| min_ce_len | -| Maximum_CE_Length | Informative parameter providing the Controller with the expected maximum length of the connection event | max_ce_len | -| Duration | Number of milliseconds before aborting the connect attempt | dur | - -### Advertisment Parameters - -| *bletiny string* | *Description* | *Notes* | *Default* | -|------------------|---------------|---------|-----------| -| conn | Connectable mode | See Connectable Modes table. | und | -| disc | Discoverable mode | See Discoverable Modes table. | gen | -| own_addr_type | The type of address to advertise with | See Address Types table. | public | -| peer_addr_type | The peer's address type | Only used for directed advertising; see Address Types table. | public | -| peer_addr | The peer's address | Only used for directed advertising | N/A | -| chan_map | | | 0 | -| filt | The filter policy | See Advertisement Filter Policies table. | none | -| itvl_min | | units=0.625ms | non: 100ms; und/dir: 30ms | -| itvl_max | | units=0.625ms | non: 150ms; und/dir: 60ms | -| hd | Whether to use high-duty-cycle | 0/1 | 0 | -| dur | | Milliseconds | Forever | - -### Advertisement Filter Policies +|LE_Scan_Interval | Recommendation from the Host on how long the Controller should scan | scan_itvl | +|LE_Scan_Window |Recommendation from the Host on how frequently the Controller should scan | scan_window | +|Minimum_CE_Length | Informative parameter providing the Controller with the expected minimum length of the connection event| min_ce_len | +|Maximum_CE_Length |Informative parameter providing the Controller with the expected maximum length of the connection event | max_ce_len | -| *bletiny string* | *Description* | *Notes* | -| -----------------|---------------|---------| -| none | No filtering. No whitelist used. | Default | -| scan | Process all connection requests but only scans from white list. | | -| conn | Process all scan request but only connection requests from white list. | | -| both | Ignore all scan and connection requests unless in white list. | | +### Advertisement data fields http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/network/ble/bletiny/bletiny_GATT.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/bletiny/bletiny_GATT.md b/docs/network/ble/bletiny/bletiny_GATT.md index 7469eb6..84ab2ac 100644 --- a/docs/network/ble/bletiny/bletiny_GATT.md +++ b/docs/network/ble/bletiny/bletiny_GATT.md @@ -3,52 +3,30 @@ <br> GATT(GENERIC ATTRIBUTE PROFILE) describes a service framework using the Attribute Protocol for discovering services, and for reading and writing characteristic values on a peer device. There are 11 features defined in the GATT Profile, and each of the features is mapped to procedures and sub-procedures: - - -|**Item No.** | **Feature** | **Sub-Procedure** | **nimBLE command** | -|----|---------|---------------|------| -| 1 | Server Configuration | Exchange MTU | `b mtu` | -| 2 | Primary Service Discovery | Discover All Primary Services | `b disc svc conn=x` | +|**Item No.** | **Feature** | **Sub-Procedure** | **nimBLE command** ||----|---------|---------------|------|| 1 | Server Configuration | Exchange MTU | `b mtu` | | 2 | Primary Service Discovery | Discover All Primary Services | `b disc svc conn=x` | | | | Discover Primary Services By Service UUID | `b disc svc conn=x uuid=x` | -| 3 | Relationship Discovery | Find Included Services | `b find inc_svcs conn=x start=x end=x` | -| 4 | Characteristic Discovery | Discover All Characteristic of a Service | `b disc chr conn=x start=x end=x` | -| | | Discover Characteristic by UUID | `b disc chr conn=x start=x end=x uuid=x` | -| 5 | Characteristic Descriptor Discovery | Discover All Characteristic Descriptors | `b disc dsc conn=x start=x end=x` | -| 6 | Reading a Characteristic Value | Read Characteristic Value | `b read conn=x attr=x` | -| | | Read Using Characteristic UUID | `b read conn=x start=x end=x uuid=x` | -| | | Read Long Characteristic Values | `b read conn=x attr=x long=1` | -| | | Read Multiple Characteristic Values | `b read conn=x attr=x attr=y attr=z` | -| 7 | Writing a Characteristic Value | Write Without Response | `b write conn=x value=0xXX:0xXX no_rsp=1` | -| | | Signed Write Without Response | NOT SUPPORTED | -| | | Write Characteristic Value | `b write conn=x attr=x value=0xXX:0xXX` | -| | | Write Long Characteristic Values | `b write conn=x attr=x value=0xXX:0xXX long=1` | -| | | Characteristic Value Reliable Writes | `b write conn=x attr=x value=0xXX:0xXX attr=y value=0xYY:0xYY` | -| 8 | Notification of a Characteristic Value | Notifications | Write _0x01:0x00_ to CLIENT CONFIGURATION characteristic | -| 9 | Indication of a Characteristic Value | Indications | Write _0x02:0x00_ to CLIENT CONFIGURATION characteristic | -| 10| Reading a Characteristic Descriptor | Read Characteristic Descriptors | `b read conn=x attr=x` | -| | | Read Long Characteristic Descriptors | `b read conn=x attr=x long=1` | -| 11| Writing a Characteristic Descriptor | Write Characteristic Descriptors | `b write conn=x value=0xXX:0xXX` | -| | | Write Long Characteristic Descriptors | `b write conn=x value=0xXX:0xXX long=1` | - - -<br> - -### Using NimBLE commands - - -Assuming you have discovered and established a BLE connection with at least one peer device (as explained earlier in [API for bletiny app](bletiny_api.md), you can find out what characteristics and services are available over these connections. Here is a recap. - -To show established connections: -``` +| 3 | Relationship Discovery | Find Included Services | `b find inc_svcs conn=x start=x end=x` || 4 | Characteristic Discovery | Discover All Characteristic of a Service | `b disc chr conn=x start=x end=x` | +| | | Discover Characteristic by UUID | `b disc chr conn=x start=x end=x uuid=x` || 5 | Characteristic Descriptor Discovery | Discover All Characteristic Descriptors | `b disc dsc conn=x start=x end=x` || 6 | Reading a Characteristic Value | Read Characteristic Value | `b read conn=x attr=x` | +| | | Read Using Characteristic UUID | `b read conn=x start=x end=x uuid=x` || | | Read Long Characteristic Values | `b read conn=x attr=x long=1` || | | Read Multiple Characteristic Values | `b read conn=x attr=x attr=y attr=z` | +| 7 | Writing a Characteristic Value | Write Without Response | `b write conn=x value=0xXX:0xXX no_rsp=1` || | | Signed Write Without Response | NOT SUPPORTED || | | Write Characteristic Value | `b write conn=x attr=x value=0xXX:0xXX` || | | Write Long Characteristic Values | `b write conn=x attr=x value=0xXX:0xXX long=1` || | | Characteristic Value Reliable Writes | `b write conn=x attr=x value=0xXX:0xXX attr=y value=0xYY:0xYY` || 8 | Notification of a Characteristic Value | Notifications | Write CLIENT CONFIGURATION characteristic || 9 | Indication of a Characteristic Value | Indications | Write CLIENT CONFIGURATION characteristic || 10| Reading a Characteristic Descriptor | Read Characteristic Descriptors | `b read conn=x attr=x` | +| | | Read Long Characteristic Descriptors | `b read conn=x attr=x long=1` || 11 | Writing a Characteristic Descriptor | Write Characteristic Descriptors | `b write conn=x value=0xXX:0xXX` | +| | | Write Long Characteristic Descriptors | `b write conn=x value=0xXX:0xXX long=1` |<br> +### Using nimBLE commands +Assuming you have discovered and established a BLE connection with at least one peer device (as explained earlier in [API for bletiny app](../bletiny_api.md), you can find out what characteristics and services are available over these connections. Here is a recap. +``` b show conn ``` +To show discovered services +``` +b show svc +``` -To show discovered services, characteristics, and descriptors: +To show discovered characteristics ``` b show chr ``` -To show connection RSSI: +To show connection RSSI ``` b show rssi conn=x -``` +``` \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/network/ble/bletiny/bletiny_advdata.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/bletiny/bletiny_advdata.md b/docs/network/ble/bletiny/bletiny_advdata.md index d2480bc..215232e 100644 --- a/docs/network/ble/bletiny/bletiny_advdata.md +++ b/docs/network/ble/bletiny/bletiny_advdata.md @@ -5,21 +5,12 @@ This part defines the advertisement data fields used in the `bletiny` app. For a complete list of all data types and formats used for Extended Inquiry Response (EIR), Advertising Data (AD), and OOB data blocks, refer to the Supplement to the Bluetooth Core Specification, CSSv6, available for download [here](https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=302735&_ga=1.133090766.1368218946.1444779486). - -<br> - - - -|**Name** | **Definition** | **Details** | **bletiny Notes** | -|----|---------|---------------|--| -| flags | Indicates basic information about the advertiser. | Flags used over the LE physical channel are: <br> * Limited Discoverable Mode <br> * General Discoverable Mode <br> * BR/EDR Not Supported <br> * Simultaneous LE and BR/EDR to Same Device Capable (Controller) <br> * Simultaneous LE and BR/EDR to Same Device Capable (Host) | NimBLE will auto-calculate if set to 0. | -| uuids16 |16-bit Bluetooth Service UUIDs | Indicates the Service UUID list is incomplete i.e. more 16-bit Service UUIDs available. 16 bit UUIDs shall only be used if they are assigned by the Bluetooth SIG. | Set repeatedly for multiple service UUIDs. | -| uuids16_is_complete | 16-bit Bluetooth Service UUIDs | Indicates the Service UUID list is complete. 16 bit UUIDs shall only be used if they are assigned by the Bluetooth SIG. | -| uuids32 | 32-bit Bluetooth Service UUIDs | Indicates the Service UUID list is incomplete i.e. more 32-bit Service UUIDs available. 32 bit UUIDs shall only be used if they are assigned by the Bluetooth SIG. | Set repeatedly for multiple service UUIDs. | -| uuids32_is_complete | 32-bit Bluetooth Service UUIDs | Indicates the Service UUID list is complete. 32 bit UUIDs shall only be used if they are assigned by the Bluetooth SIG. | -| uuids128 | Global 128-bit Service UUIDs | More 128-bit Service UUIDs available. | Set repeatedly for multiple service UUIDs. | -| uuids128_is_complete | Global 128-bit Service UUIDs | Complete list of 128-bit Service UUIDs | -| tx_pwr_lvl | TX Power Level | Indicates the transmitted power level of the packet containing the data type. The TX Power Level data type may be used to calculate path loss on a received packet using the following equation: <br> <br> pathloss = Tx Power Level â RSSI <br> <br> where âRSSIâ is the received signal strength, in dBm, of the packet received. | NimBLE will auto-calculate if set to -128. | +<br> +|**Name** | **Definition** | **Details** ||----|---------|---------------| +| uuids16 |16-bit Bluetooth Service UUIDs | Indicates the Service UUID list is incomplete i.e. more 16-bit Service UUIDs available. 16 bit UUIDs shall only be used if they are assigned by the Bluetooth SIG. || uuids16_is_complete | 16-bit Bluetooth Service UUIDs | Indicates the Service UUID list is complete. 16 bit UUIDs shall only be used if they are assigned by the Bluetooth SIG. | +| uuids32 | 32-bit Bluetooth Service UUIDs | Indicates the Service UUID list is incomplete i.e. more 32-bit Service UUIDs available. 32 bit UUIDs shall only be used if they are assigned by the Bluetooth SIG. || uuids32_is_complete | 32-bit Bluetooth Service UUIDs | Indicates the Service UUID list is complete. 32 bit UUIDs shall only be used if they are assigned by the Bluetooth SIG. | +| uuids128 | Global 128-bit Service UUIDs | More 128-bit Service UUIDs available. || uuids128_is_complete | Global 128-bit Service UUIDs | Complete list of 128-bit Service UUIDs | +| tx_pwr_lvl | TX Power Level | Indicates the transmitted power level of the packet containing the data type. The TX Power Level data type may be used to calculate path loss on a received packet using the following equation: <br> <br> pathloss = Tx Power Level â RSSI <br> <br> where âRSSIâ is the received signal strength, in dBm, of the packet received. | | device_class | Class of device | Size: 3 octets | | slave_itvl_range | Slave Connection Interval Range | Contains the Peripheralâs preferred connection interval range, for all logical connections. Size: 4 Octets . The first 2 octets defines the minimum value for the connection interval in the following manner: <br> <br> connIntervalmin = Conn_Interval_Min * 1.25 ms <br> <br> Conn_Interval_Min range: 0x0006 to 0x0C80 <br> Value of 0xFFFF indicates no specific minimum. <br> <br> The other 2 octets defines the maximum value for the connection interval in the following manner: <br> <br> connIntervalmax = Conn_Interval_Max * 1.25 ms <br> Conn_Interval_Max range: 0x0006 to 0x0C80 <br> Conn_Interval_Max shall be equal to or greater than the Conn_Interval_Min. <br> Value of 0xFFFF indicates no specific maximum.| | svc_data_uuid16 | Service Data - 16 bit UUID | Size: 2 or more octets <br> The first 2 octets contain the 16 bit Service UUID followed by additional service data | @@ -31,8 +22,5 @@ This part defines the advertisement data fields used in the `bletiny` app. For a | svc_data_uuid32 | Service Data - 32 bit UUID | Size: 4 or more octets <br> The first 4 octets contain the 32 bit Service UUID followed by additional service data | | svc_data_uuid128 | Service Data - 128 bit UUID | Size: 16 or more octets <br> The first 16 octets contain the 128 bit Service UUID followed by additional service data | | uri | Uniform Resource Identifier (URI) | Scheme name string and URI as a UTF-8 string | -| mfg_data | Manufacturer Specific data | Size: 2 or more octets <br> The first 2 octets contain the Company Identifier Code followed by additional manufacturer specific data | -| eddystone_url | | | - -<br> - +| mfg_data | Manufacturer Specific data | Size: 2 or more octets <br> The first 2 octets contain the Company Identifier Code followed by additional manufacturer specific data |<br> + \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/network/ble/bletiny_api.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/bletiny_api.md b/docs/network/ble/bletiny_api.md new file mode 100644 index 0000000..a20b96a --- /dev/null +++ b/docs/network/ble/bletiny_api.md @@ -0,0 +1,144 @@ +## API for bletiny app + +"bletiny" is one of the sample applications that come with Mynewt. It is a simple shell application which provides a basic interface to the host-side of the BLE stack. "bletiny" includes all the possible roles (Central/Peripheral) and they may be run simultaneously. You can run bletiny on a board and issue commands that make it behave as a central or a peripheral with different peers. + +Highlighted below are some of the ways you can use the API to establish connections and discover services and characteristics from peer devices. For descriptions of the full API, go to the next sections on [GAP in bletiny](bletiny/bletiny_GAP.md) and [GATT in bletiny](bletiny/bletiny_GATT.md). + +<br> + +### Set device public address. + +Currently the device public address is hardcoded to `0a:0b:0c:0d:0e:0f` in `bletiny` app but you can change it by going into its source code and initializing it to the desired value as described in the section on how to [initialize device addr](ini_stack/ble_devadd.md). + +<br> + +### Initiate a direct connection to a device + +In this case, your board is acting as a central and initiating a connection with another BLE device. The example assumes you know the address of the peer, either by scanning for available peers or because you have set up the peer yourself. + +```hl_lines="1" +b conn addr_type=public addr=d4:f5:13:53:d2:43 +[ts=118609ssb, mod=64 level=2] connection complete; status=0 handle=1 peer_addr_type=0 peer_addr=0x43:0xd2:0x53:0x13:0xf5:0xd4 conn_itvl=40 conn_latency=0 supervision_timeout=256 +``` + +The `handle=1` in the output indicates that it is connection-1. + +<br> + +### Configure advertisements to include device name + +In this case, your board is acting as a peripheral. + +``` +b set adv_data name=<your-device-name> +``` + +<br> + +### Begin sending undirected general advertisements + +In this case, your board is acting as a peripheral. + +``` +b adv conn=und disc=gen +``` + +<br> + +### Show established connections. + +``` +b show conn +``` + +<br> + +### Discover and display peer's services. + +This is how you discover and then display the services of the peer you established earlier across connection-1. + +```hl_lines="1 2" +b disc svc conn=1 +b show chr +[ts=132425ssb, mod=64 level=2] CONNECTION: handle=1 addr=d4:f5:13:53:d2:43 +[ts=132428ssb, mod=64 level=2] start=1 end=5 uuid=0x1800 +[ts=132433ssb, mod=64 level=2] start=6 end=16 uuid=0x1808 +[ts=132437ssb, mod=64 level=2] start=17 end=31 uuid=0x180a +[ts=132441ssb, mod=64 level=2] start=32 end=65535 uuid=00000000-0000-1000-1000000000000000 +``` + +<br> + +### Discover characteristics for each service on peer + +The following examples show how to find the characteristics for each service available on the peer device across connection-1. The start and end values depend on the specific services discovered using the previous command `b show chr`. Continuing with the example above, you can discover the characteristics of the first service and display it using the following commands. + +```hl_lines="1 2" +b disc chr conn=1 start=1 end=5 +b show chr +[ts=163063ssb, mod=64 level=2] CONNECTION: handle=1 addr=d4:f5:13:53:d2:43 +[ts=163067ssb, mod=64 level=2] start=1 end=5 uuid=0x1800 +[ts=163071ssb, mod=64 level=2] def_handle=2 val_handle=3 properties=0x02 uuid=0x2a00 +[ts=163078ssb, mod=64 level=2] def_handle=4 val_handle=5 properties=0x02 uuid=0x2a01 +[ts=163085ssb, mod=64 level=2] start=6 end=16 uuid=0x1808 +[ts=163089ssb, mod=64 level=2] start=17 end=31 uuid=0x180a +[ts=163094ssb, mod=64 level=2] start=32 end=65535 uuid=00000000-0000-1000-1000000000000000 +``` + +You can next discover characteristics for the second service and display. + +```hl_lines="1 2" +b disc chr conn=1 start=6 end=16 +b show chr +[ts=180631ssb, mod=64 level=2] CONNECTION: handle=1 addr=d4:f5:13:53:d2:43 +[ts=180634ssb, mod=64 level=2] start=1 end=5 uuid=0x1800 +[ts=180639ssb, mod=64 level=2] def_handle=2 val_handle=3 properties=0x02 uuid=0x2a00 +[ts=180646ssb, mod=64 level=2] def_handle=4 val_handle=5 properties=0x02 uuid=0x2a01 +[ts=180653ssb, mod=64 level=2] start=6 end=16 uuid=0x1808 +[ts=180657ssb, mod=64 level=2] def_handle=7 val_handle=8 properties=0x10 uuid=0x2a18 +[ts=180664ssb, mod=64 level=2] def_handle=10 val_handle=11 properties=0x02 uuid=0x2a51 +[ts=180672ssb, mod=64 level=2] def_handle=12 val_handle=13 properties=0x28 uuid=0x2a52 +[ts=180679ssb, mod=64 level=2] def_handle=15 val_handle=16 properties=0x02 uuid=0x2a08 +[ts=180686ssb, mod=64 level=2] start=17 end=31 uuid=0x180a +[ts=180691ssb, mod=64 level=2] start=32 end=65535 uuid=00000000-0000-1000-1000000000000000 +``` + +<br> + +### Discover descriptors for each characteristic on peer + +Just as before, the start and end values depend on the specific characteristics discovered. + +``` +b disc dsc conn=1 start=1 end=5 +b disc dsc conn=1 start=6 end=16 +b disc dsc conn=1 start=17 end=31 +``` + +<br> + +### Read an attribute belonging to the peer + +``` +b read conn=1 attr=18 attr=21 +``` + +<br> + +### Write to an attribute belonging to the peer + +``` +b write conn=1 attr=3 value=0x01:0x02:0x03 +``` + +<br> + +### Perform a passive scan + +This is how you tell your board to listen to all advertisements around it. The duration is specified in ms. + +``` +b scan dur=1000 disc=gen type=passive filt=no_wl +``` + +<br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/network/ble/ini_stack/ble_parent_ini.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ini_stack/ble_parent_ini.md b/docs/network/ble/ini_stack/ble_parent_ini.md index 6928ef5..37054c5 100644 --- a/docs/network/ble/ini_stack/ble_parent_ini.md +++ b/docs/network/ble/ini_stack/ble_parent_ini.md @@ -6,7 +6,7 @@ application-specific work, the host parent task does work for NimBLE by processing events generated by the host. The process of creating an OS task is described in the [Add Task -tutorial](../../../os/tutorials/event_queue/). +tutorial](#../../../../os/tutorials/event_queue/). **Priority:** It is up to you which priority to use for the host parent task. Unlike the http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/newt/install/newt_linux.md ---------------------------------------------------------------------- diff --git a/docs/newt/install/newt_linux.md b/docs/newt/install/newt_linux.md index 8029662..6f2509b 100644 --- a/docs/newt/install/newt_linux.md +++ b/docs/newt/install/newt_linux.md @@ -134,27 +134,4 @@ If you want to build the *newt* tool from its source code, follow the following <br> -#### 5. Updating the Newt tool - -* You will update the newt tool in the same place as you initially installed the newt tool. -* Start by updating the git repository of the newt tool (you can change to a different branch using git checkout [branch] if you need to) -* Then update each of the tools newt, newtmgr and newtvm as needed - -```no-highlight - $ cd $GOPATH/src/mynewt.apache.org/newt - $ git pull - $ cd newt - $ go install - $ cd ../newtmgr - $ go install - $ cd ../newtvm - $ go install - $ ls "$GOPATH"/bin/ - newt newtmgr newtvm -``` - -That should have updated your newt, newtmgr and newtvm to the latest versions based on the git repository you used. - -<br> - http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/newt/install/newt_mac.md ---------------------------------------------------------------------- diff --git a/docs/newt/install/newt_mac.md b/docs/newt/install/newt_mac.md index f1eb586..0da1503 100644 --- a/docs/newt/install/newt_mac.md +++ b/docs/newt/install/newt_mac.md @@ -139,28 +139,3 @@ If you want to build the *newt* tool from its source code, follow the following Use "newt help [command]" for more information about a command. ``` -<br> - -#### 5. Updating the Newt tool - -* You will update the newt tool in the same place as you initially installed the newt tool. -* Start by updating the git repository of the newt tool (you can change to a different branch using git checkout [branch] if you need to) -* Then update each of the tools newt, newtmgr and newtvm as needed - -```no-highlight - $ cd $GOPATH/src/mynewt.apache.org/newt - $ git pull - $ cd newt - $ go install - $ cd ../newtmgr - $ go install - $ cd ../newtvm - $ go install - $ ls "$GOPATH"/bin/ - newt newtmgr newtvm -``` - -That should have updated your newt, newtmgr and newtvm to the latest versions based on the git repository you used. - -<br> - http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/newt/newt_intro.md ---------------------------------------------------------------------- diff --git a/docs/newt/newt_intro.md b/docs/newt/newt_intro.md index f736b09..89a7922 100644 --- a/docs/newt/newt_intro.md +++ b/docs/newt/newt_intro.md @@ -187,18 +187,7 @@ pkg.deps: <br> -### Autocompletion in Bash -Newt has the ability to autocomplete within `bash`. The following instructions allow MAC users to enable autocomplete within `bash`. - -1. Install the autocomplete tools for bash via `brew install bash-completion` -2. Tell your shell to use newt for autocompletion of newt via `complete -C "newt complete" newt`. You can add this to your .bashrc or other init file to have it automatically set for all bash shells. - -Notes: - -1. Autocomplete will give you flag hints, but only if you type a '-'. -2. Autocomplete will not give you completion hints for the flag arguments (those optional things after the flag like `-l DEBUG`) -3. Autocomplete uses newt to parse the project to find targets and libs. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/os/core_os/porting/port_bsp.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/porting/port_bsp.md b/docs/os/core_os/porting/port_bsp.md index 1a34a9d..4747589 100644 --- a/docs/os/core_os/porting/port_bsp.md +++ b/docs/os/core_os/porting/port_bsp.md @@ -1,5 +1,5 @@ -#Create a BSP for your Target +#Create a BSP for your Target ###Introduction @@ -24,8 +24,8 @@ Select a name for your BSP. For the remainder of this document, we'll assume th Create a directory `hw/bsp/myboard` using the name chosen above. Within this BSP directory, create the following subdirectories: -Select a name for your BSP. For the remainder of this document, -well assume the bsp is named `myboard`. In general its best to select a +Select a name for your BSP. For the remainder of this document, +well assume the bsp is named `myboard`. In general its best to select a name that describes the board/system you are creating. * `include` @@ -34,7 +34,7 @@ name that describes the board/system you are creating. ###Create a Target using Mynewt -Create a newt target for your test project for the BSP. To learn how to create a target, see this **howto** [Tutorial](../../get_started/project_create). Once you are familiar with creating targets, move on below to create a target to use to test your BSP. +Create a newt target for your test project for the BSP. To learn how to create a target, see this **howto** [Tutorial](../../get_started/project1). Once you are familiar with creating targets, move on below to create a target to use to test your BSP. It is recommended that you use a simple `project` like `blinky` to minimize time to get a working Mynewt system. For this document, we will assume the `target` is called `myboard_blinky` and uses project `blinky`. @@ -43,7 +43,7 @@ Set the `bsp` of the project to `/hw/bsp/myboard`. While creating your target, y When you are complete, your `target` may look similar to this. ```c - $newt target show + $newt target show myboard_blinky arch=cortex_m0 bsp=hw/bsp/myboard @@ -80,7 +80,7 @@ Optionally, create these files as necessary to provide all functionality from My ###Fill Out your Package File -Edit the package file to describe your BSP. +Edit the package file to describe your BSP. The package file must contain: @@ -102,7 +102,7 @@ The package file typically contains: pkg.linkerscript.bootloader.OVERWRITE: "myboard_boot.ld" pkg.downloadscript: "myboard_download.sh" pkg.debugscript: "myboard_debug.sh" - pkg.deps: + pkg.deps: - hw/mcu/mymcu/variant ``` where `mymcu/variant` should be replaced with the specific MCU and variant used in your design. @@ -160,7 +160,7 @@ Create an alternate linker script for the bootloader since it is typically linke ###Add Functions and Defines -At this point, it will be possible to run the `newt` tool to build your target. +At this point, it will be possible to run the `newt` tool to build your target. You may run into complaints from the linker script that a few Mynewt specific functions are missing. We will describe these below. @@ -173,7 +173,7 @@ There are also several libc definitions that can be stubbed in your first BSP. E | **Function** | **Description** | |-----------|-------------| -| _sbrk | Returns memory from heap (used by malloc) | +| _sbrk | Returns memory from heap (used by malloc) | * Implement `_sbrk()` @@ -232,5 +232,5 @@ The `LICENSE` file is an ASCII text file that describes the source license for t package. The `README.md` is a [markdown](https://en.wikipedia.org/wiki/Markdown) - file that contains any documentation you + file that contains any documentation you want to provide for the BSP. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/os/core_os/porting/port_os.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/porting/port_os.md b/docs/os/core_os/porting/port_os.md index 0784fc4..1a3b779 100644 --- a/docs/os/core_os/porting/port_os.md +++ b/docs/os/core_os/porting/port_os.md @@ -1,35 +1,35 @@ # Porting Mynewt OS -This chapter describes how to adapt the Mynewt OS to different platforms. +This chapter describes how to adapt the Mynewt OS to different platforms. ###Description -The Mynewt OS is a complete multi-tasking environment with scheduler, time -control, buffer management, and synchronization objects. it also includes -libraries and services like console, command shell, image manager, +The Mynewt OS is a complete multi-tasking environment with scheduler, time +control, buffer management, and synchronization objects. it also includes +libraries and services like console, command shell, image manager, bootloader, and file systems etc. Thee majority of this software is platform independent and requires no -intervention to run on your platform, but some of the components require -support from the underlying platform. +intervention to run on your platform, but some of the components require +support from the underlying platform. The platform dependency of these components can fall into several categories: -* **CPU Core Dependencies** -- Specific code or +* **CPU Core Dependencies** -- Specific code or configuration to operate the CPU core within your target platform -* **MCU Dependencies** -- Specific code or configuration to operate the MCU or +* **MCU Dependencies** -- Specific code or configuration to operate the MCU or SoC within your target platform -* **BSP Dependencies** -- Specific code or configuration to accommodate the -specific layout and functionality of your target platform +* **BSP Dependencies** -- Specific code or configuration to accommodate the +specific layout and functionality of your target platform ###BSP Dependency -With all of the functionality provided by the core, MCU, and MCU HAL (Hardware Abstraction Layer), there are still some things that must be specified for your particular system. This +With all of the functionality provided by the core, MCU, and MCU HAL (Hardware Abstraction Layer), there are still some things that must be specified for your particular system. This is provided in Mynewt to allow you the flexibility to design for the exact functionality, peripherals and features that you require in your product. -In Mynewt, these settings/components are included in a Board Support Package -(BSP). The BSP contains the information specific to running Mynewt on a target +In Mynewt, these settings/components are included in a Board Support Package +(BSP). The BSP contains the information specific to running Mynewt on a target platform or hardware board. Mynewt supports some common open source hardware as well as the development boards for some common MCUs. These development systems might be enough for you to get your prototype up and running, but when building @@ -37,13 +37,13 @@ a product you are likely going to have your own board which is slightly differen from those already supported by Mynewt. For example, you might decide on your system that 16 Kilobytes of flash space -in one flash device is reserved for a flash file system. Or on your system +in one flash device is reserved for a flash file system. Or on your system you may decide that GPIO pin 5 of the MCU is connected to the system LED. Or you may decide that the OS Tick (the underlying time source for the OS) should -run slower than the defaults to conserve battery power. These types of +run slower than the defaults to conserve battery power. These types of behaviors are specified in the BSP. -The information provided in the BSP (what you need to specify to get a +The information provided in the BSP (what you need to specify to get a complete executable) can vary depending on the MCU and its underlying core architecture. For example, some MCUs have dedicated pins for UART, SPI etc, so there is no configuration required in the BSP when using these peripherals. @@ -51,14 +51,14 @@ However some MCUs have a pin multiplexor that allows the UART to be mapped to several different pins. For these MCUs, the BSP must specify if and where the UART pins should appear to match the hardware layout of your system. -* If your BSP is already supported my Mynewt, there is no additional BSP work involved in porting to your platform. You need only to set the `bsp` attribute in your Mynewt target using the [newt command tool](../../../newt/newt_intro). +* If your BSP is already supported my Mynewt, there is no additional BSP work involved in porting to your platform. You need only to set the `bsp` attribute in your Mynewt target using the [newt command tool](../../../../newt/newt_intro). * If your BSP is not yet supported by Mynewt, you can add support following the instructions on [how to add BSP support to Mynewt](port_bsp.md) ###MCU Dependency Some OS code depends on the MCU or SoC that the system contains. For example, the MCU may specify the potential memory map of the system - where code and data can reside. -* If your MCU is already supported my Mynewt, there is no additional MCU work involved in porting to your platform. You need only to set the `arch` attribute in your Mynewt target using the [newt command tool](../../../newt/newt_intro). +* If your MCU is already supported my Mynewt, there is no additional MCU work involved in porting to your platform. You need only to set the `arch` attribute in your Mynewt target using the [newt command tool](../../../../newt/newt_intro). * If your MCU is not yet supported by Mynewt, you can add support following the instructions on[how to add MCU support to Mynewt](port_mcu.md) @@ -67,9 +67,10 @@ Some OS code depends on the MCU or SoC that the system contains. For example, th Mynewt's architecture supports a hardware abstraction layer (HAL) for common on or off-chip MCU peripherals such as GPIO, UARTs, flash memory etc. Even if your MCU is supported for the core OS, you may find that you need to implement the HAL functionality for a new peripheral. For a description of the HAL abstraction and implementation information, see the [HAL API](../../modules/hal/hal.md) -###CPU Core Dependency +###CPU Core Dependency Some OS code depends on the CPU core that your system is using. For example, a given CPU core has a specific assembly language instruction set, and may require special cross compiler or compiler settings to use the appropriate instruction set. -* If your CPU architecture is already supported my Mynewt, there is no CPU core work involved in porting to your platform. You need only to set the `arch` and `compiler` attributes in your Mynewt target using the [newt command tool](../../../newt/newt_intro). +* If your CPU architecture is already supported my Mynewt, there is no CPU core work involved in porting to your platform. You need only to set the `arch` and `compiler` attributes in your Mynewt target using the [newt command tool](../../../../newt/newt_intro). * If your CPU architecture is not supported by Mynewt, you can add support following the instructions on [how to add CPU architecture support to Mynewt](port_cpu.md) + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/os/core_os/time/os_time_tick.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/time/os_time_tick.md b/docs/os/core_os/time/os_time_tick.md index 1c217e1..420aa23 100644 --- a/docs/os/core_os/time/os_time_tick.md +++ b/docs/os/core_os/time/os_time_tick.md @@ -1,10 +1,10 @@ ## <font color="F2853F" style="font-size:24pt">os_time_tick</font> ```c -void os_time_tick(void) +void os_time_tick(void) ``` -Increments the OS time tick for the system. Typically, this is called in one place by the architecture specific OS code (`libs/os/arch`) `timer_handler` which is in turn called by the BSP specific code assigned to drive the OS timer tick. See [Porting Mynewt OS](../porting/port_os) for details. +Increments the OS time tick for the system. Typically, this is called in one place by the architecture specific OS code (`libs/os/arch`) `timer_handler` which is in turn called by the BSP specific code assigned to drive the OS timer tick. See [Porting Mynewt OS](../port_os) for details. #### Arguments @@ -14,7 +14,7 @@ N/A N/A -#### Notes +#### Notes Called for every single tick by the architecture specific functions. @@ -25,3 +25,5 @@ Called for every single tick by the architecture specific functions. ```c os_time_tick(); ``` + + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/os/introduction.md ---------------------------------------------------------------------- diff --git a/docs/os/introduction.md b/docs/os/introduction.md index 4d83372..22df5c9 100644 --- a/docs/os/introduction.md +++ b/docs/os/introduction.md @@ -3,14 +3,14 @@ ### Welcome to Apache Mynewt Apache Mynewt is an operating system that makes it easy to develop -applications for microcontroller environments where power and cost -are driving factors. Examples of these devices are connected locks, +applications for microcontroller environments where power and cost +are driving factors. Examples of these devices are connected locks, lights, and wearables. -Microcontroller environments have a number of characteristics that -makes the operating system requirements for them unique: +Microcontroller environments have a number of characteristics that +makes the operating system requirements for them unique: -* Low memory footprint: memory on these systems range from +* Low memory footprint: memory on these systems range from 8-16KB (on the low end) to 16MB (on the high end). * Reduced code size: code often runs out of flash, and total available code size ranges from 64-128KB to 16-32MB. @@ -22,7 +22,7 @@ battery power and maximize power usage. As more and more devices get connected, these interconnected devices perform complex tasks. To perform these tasks, you need low-level operational functionality built into the operating system. -Typically, connected devices built with these microcontrollers perform a myriad of functions: +Typically, connected devices built with these microcontrollers perform a myriad of functions: * Networking Stacks: Bluetooth Low Energy and Thread @@ -34,23 +34,23 @@ to keep time. Apache Mynewt accomplishes all the above easily, by providing a complete operating system for constrained devices, including: -* A fully open-source Bluetooth Low Energy stack with both Host and -Controller implementations. +* A fully open-source Bluetooth Low Energy stack with both Host and +Controller implementations. * A pre-emptive, multi-tasking Real Time operating system kernel -* A Hardware Abstraction Layer (HAL) that abstracts the MCU's +* A Hardware Abstraction Layer (HAL) that abstracts the MCU's peripheral functions, allowing developers to easily write cross-platform code. <br> ### Newt ### -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*. +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](../newt/install/newt_linux/) or [Mac](../newt/install/newt_mac/). +You can install and build *newt* for [Linux](..//newt/install/newt_linux/) or [Mac](../newt/install/newt_mac/). <br> @@ -59,13 +59,13 @@ You can install and build *newt* for [Linux](../newt/install/newt_linux/) or [Ma In order to enable a user to communicate with remote instances of Mynewt OS and query, configure, and operate them, Mynewt provides an application tool called Newt Manager or `newtmgr`. -You can install and build *newtmgr* from source code on [Linux or Mac](../newtmgr/installing/). +You can install and build *newtmgr* from source code on [Linux or Mac](../newtmgr/installing/). <br> ### Build your first Mynewt App with Newt ### -With the introductions out of the way, now is a good time to [get set up and -started](get_started/get_started/) with your first Mynewt application. +With the introductions out of the way, now is a good time to [get set up and +started](../get_started/get_started/) with your first Mynewt application. Happy Hacking! http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/os/modules/hal/hal_cputime/hal_cpu_timer.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/hal/hal_cputime/hal_cpu_timer.md b/docs/os/modules/hal/hal_cputime/hal_cpu_timer.md index d430dfc..99fa830 100644 --- a/docs/os/modules/hal/hal_cputime/hal_cpu_timer.md +++ b/docs/os/modules/hal/hal_cputime/hal_cpu_timer.md @@ -7,7 +7,7 @@ The hardware independent interface to system time. Contains several different interface. -* An interface to get the current CPU time +* An interface to get the current CPU time * Interfaces to convert between CPU time and clock time (microseconds etc.) * An Interface to set up a software timer based on CPU time. @@ -17,13 +17,15 @@ Contains several different interface. ###CPU Time -The CPU time is not the same as the [os_time](). Typically, +The CPU time is not the same as the [os_time](TBD). Typically, the os_time is set to a much slower tick rate than the CPU time. The CPU time should be used for timing real-time events at exact times. The os_time -should be used for system level timeout etc that are not in fine time +should be used for system level timeout etc that are not in fine time resolutions. In fact, cputime is not part of the os at all, but a hardware -layer abstraction to high resolution timers. +layer abstraction to high resolution timers. -There are methods to get the cputime as 32-bit and 64-bit values. Both +There are methods to get the cputime as 32-bit and 64-bit values. Both values may eventually wrap, but for timing short events a 32-bit value -may be sufficient and would +may be sufficient and would + + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/os/modules/hal/hal_gpio/hal_gpio.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/hal/hal_gpio/hal_gpio.md b/docs/os/modules/hal/hal_gpio/hal_gpio.md index a8d6af6..5518bc8 100644 --- a/docs/os/modules/hal/hal_gpio/hal_gpio.md +++ b/docs/os/modules/hal/hal_gpio/hal_gpio.md @@ -8,20 +8,20 @@ This is the hardware independent GPIO (General Purpose Input Output) Interface f Contains the basic operations to set and read General Purpose Digital I/O Pins within a Mynewt system. -Individual GPIOs are referenced in the APIs as `pins`. However, in this interface the `pins` are virtual GPIO pins. The MCU hal driver maps these virtual `pins` to the physical GPIO ports and pins. +Individual GPIOs are referenced in the APIs as `pins`. However, in this interface the `pins` are virtual GPIO pins. The MCU hal driver maps these virtual `pins` to the physical GPIO ports and pins. Typically, the BSP code may define named I/O pins in terms of these virtual `pins` to describe the devices attached to the physical pins. Here's a brief example so you can get the gist of the translation. -Suppose my product uses the stm32F4xx processor. There already exists support for this processor within Mynewt. The processor has N ports (A,B,C..) of 16 GPIO pins per port. The MCU hal_gpio driver maps these to a set of virtual pins 0-N where port A maps to 0-15, Port B maps to 16-31, Port C maps to 32-47 and so on. The exact number of physical port (and virtual +Suppose my product uses the stm32F4xx processor. There already exists support for this processor within Mynewt. The processor has N ports (A,B,C..) of 16 GPIO pins per port. The MCU hal_gpio driver maps these to a set of virtual pins 0-N where port A maps to 0-15, Port B maps to 16-31, Port C maps to 32-47 and so on. The exact number of physical port (and virtual port pins) depends on the specific variant of the stm32F4xx. -So if I want to turn on port B pin 3, that would be virtual pin 1*16 + 3 = 19. -This translation is defined in the MCU implementation of -[hal_gpio.c](https://github.com/apache/incubator-mynewt-larva/blob/master/hw/mcu/stm/stm32f4xx/src/hal_gpio.c) -for the stmf32F4xx. Each MCU will typically have a different translation method -depending on its GPIO architecture. +So if I want to turn on port B pin 3, that would be virtual pin 1*16 + 3 = 19. +This translation is defined in the MCU implementation of +[hal_gpio.c](https://github.com/apache/incubator-mynewt-larva/blob/master/hw/mcu/stm/stm32f4xx/src/hal_gpio.c) +for the stmf32F4xx. Each MCU will typically have a different translation method +depending on its GPIO architecture. Now, when writing a BSP, it's common to give names to the relevant port pins that you are using. Thus, the BSP may define a mapping between a function and a virtual port pin. For example @@ -46,10 +46,11 @@ SYSTEM_LED --> hal_gpio virtual pin 37 --> port C pin 5 on the stm34F4xx #### Blinky -Blinky uses the hal_gpio to blink the system LED. The blinky source code is available -[here](https://github.com/apache/incubator-mynewt-core/blob/master/apps/blinky/src/main.c). +Blinky uses the hal_gpio to blink the system LED. The blinky source code is available +[here](https://github.com/apache/incubator-mynewt-larva/blob/master/project/blinky/src/main.c). Examine how `task1_handler` initializes and toggles the GPIO to control the LED. <br> --------------------- + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/32902442/docs/os/modules/split/split.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/split/split.md b/docs/os/modules/split/split.md index 0733e6f..bd54dde 100644 --- a/docs/os/modules/split/split.md +++ b/docs/os/modules/split/split.md @@ -4,18 +4,25 @@ ## Description -Split images allow the user to build the application content separate from the library content by splitting an application into two pieces: +Split images allow the user to build the application content separate from the library content by +splitting an application into two pieces: -* A "loader" which contains a separate application that can perform upgrades and manage split images. The "loader" resides in slot 1. -* A "split app" which contains the main application content and references the libraries in the loader by static linkage. The "split app" resides in slot 2. +* A "loader" which contains a separate application that can perform upgrades and manage split images. +The "loader" resides in slot 1. +* A "split app" which contains the main application content and references the libraries in the loader +by static linkage. The "split app" resides in slot 2. ## Goals -The goal of split images is to allow a larger application to run along with large components of mynewt such as [nimble BLE stack](../../../network/ble/ble_intro/) and [neutron flash file system(nffs)](../fs/nffs/nffs.md). +The goal of split images is to allow a larger application to run along with large components of +mynewt such as [nimble BLE stack](../../../network/ble/ble_intro/) and [neutron flash file system(nffs)](../fs/nffs/nffs.md). ## Concept -In a typical mynewt application, an application is contained wholly within an image slot. Typically there are at least two image slots since the image runs from one slot while uploading new code into the second slot. Each image is capable of erasing and uploading another image. Each image is completely stand-alone; that is, each image contains all of the libraries and components that it needs. +In a typical mynewt application, an application is contained wholly within an image slot. Typically +there are at least two image slots since the image runs from one slot while uploading new code into +the second slot. Each image is capable of erasing and uploading another image. Each image is completely +stand-alone; that is, each image contains all of the libraries and components that it needs. On a typical 256 kbyte flash, a flash layout might look like this: @@ -40,18 +47,25 @@ Now, suppose the desired image contains: | newtmgr | 7 k | -which total 106k. With an image slot size of 108k this leaves only a small amount of code space remaining for the application. +which total 106k. With an image slot size of 108k this leaves only a small amount of code space +remaining for the application. -However, we can see that these packages contain everything you need to upgrade and configure, so if we build a stand-alone loader with these components, we can build the app as a split image and get the entire second image slot to store application code and constant data. +However, we can see that these packages contain everything you need to upgrade and configure, so +if we build a stand-alone loader with these components, we can build the app as a split image and +get the entire second image slot to store application code and constant data. ## When do I use split images -If your application fits into the available image slots, there is no advantage to using split images. In general, split images are harder to debug and more complicated to upload. However for a larger application, there may not be enough flash space to have two copies of the entire application. This is when split image becomes necessary. +If your application fits into the available image slots, there is no advantage to using split +images. In general, split images are harder to debug and more complicated to upload. However +for a larger application, there may not be enough flash space to have two copies of the entire +application. This is when split image becomes necessary. ## How do I tell Newt I am building a split image? -Newt looks for the variable `loader` in your target file. If it finds `loader` variable, it will build a split image. For example, +Newt looks for the variable `loader` in your target file. If it finds `loader` variable, it +will build a split image. For example, ``` targets/app @@ -75,14 +89,16 @@ Split image requires BSP support. The following BSPs support split images: ## Loaders -The following applications have been enabled as loaders. You may choose to build your own loader application, and these can serve as samples. +The following applications have been enabled as loaders. You may choose to build your own loader +application, and these can serve as samples. * @apache-mynewt-core/apps/slinky * @apache-mynewt-core/apps/bleprph ## Split Apps -The following applications have been enabled as split applications. If you choose to build your own split application these can serve as samples. Note that slinky can be either a loader image or a split app image. +The following applications have been enabled as split applications. If you choose to build your own +split application these can serve as samples. Note that slinky can be either a loader image or a split app image. * @apache-mynewt-core/apps/slinky * @apache-mynewt-core/apps/splitty @@ -91,58 +107,81 @@ The following applications have been enabled as split applications. If you choos A split image is built as follows: -First newt builds the `app` and `loader` images separately to ensure they are consistent (no errors) and to generate elf files which can inform newt of the symbols used by each part. +First newt builds the `app` and `loader` images separately to ensure they are consistent (no errors) and +to generate elf files which can inform newt of the symbols used by each part. -Then newt collects the symbols used by both `app` and `loader` in two ways. It collects the set of symbols from the `.elf` files. It also collects all the possible symbols from the `.a` files for each application. +Then newt collects the symbols used by both `app` and `loader` in two ways. It collects the set of +symbols from the `.elf` files. It also collects all the possible symbols from the `.a` files for +each application. -Newt builds the set of packages that the two applications share. It ensures that all the symbols used in those packages are matching. NOTE: because of features and #ifdefs, its possible for the two package to have symbols that are not the same. In this case newt generates an error and will not build a split image. +Newt builds the set of packages that the two applications share. It ensures that all the symbols +used in those packages are matching. NOTE: because of features and #ifdefs, its possible for the +two package to have symbols that are not the same. In this case newt generates an error and will +not build a split image. Then newt creates the list of symbols that the two applications share from those packages (using the .elf files). -Newt re-links the loader to ensure all of these symbols are present in the loader application (by forcing the linker to include them in the `.elf`). +Newt re-links the loader to ensure all of these symbols are present in the loader application (by +forcing the linker to include them in the `.elf`). -Newt builds a special copy of the loader.elf with only these symbols (and the handful of symbols discussed in the linking section above). +Newt builds a special copy of the loader.elf with only these symbols (and the handful of symbols +discussed in the linking section above). -Finally, newt links the application, replacing the common .a libraries with the special loader.elf image during the link. +Finally, newt links the application, replacing the common .a libraries with the special loader.elf +image during the link. ## Design ### Bootloader -The bootloader has been modified to support "non bootable" images like split app images. A flag in the image header denotes the image as "non-bootable". When this flag is set, the bootloader will not boot the split app image, nor will it copy it to the slot 1 location. Loader images are bootable, split app images are not. +The [bootloader](../bootloader/bootloader.md) has been modified to support "non bootable" images like split app images. A flag in +the image header denotes the image as "non-bootable". When this flag is set, the bootloader will +not boot the split app image, nor will it copy it to the slot 1 location. Loader images are bootable, +split app images are not. ### Newt Newt builds a split image when the token `loader=@apache-mynewt-core/apps/slinky` is present in the target file. -Newt has a `Builder` object that is responsible for building an image. This features a `targetBuilder` object that contains two builders (one for the app and one for the loader). +Newt has a `Builder` object that is responsible for building an image. This features a `targetBuilder` +object that contains two builders (one for the app and one for the loader). The `Builder` object has been expanded to include options for building as part of a split image. * Ability to specify the linker file during the link * Ability to specify a set of keep_symbols during the link -Newt commands like download, size, create-image have been expanded to perform operations twice (once for loader and once for app) if the loader target is present. +Newt commands like download, size, create-image have been expanded to perform operations twice +(once for loader and once for app) if the loader target is present. -During normal single-image builds, the `targetBuilder` initializes and builds the application `builder`. During the split image build, the `targetBuilder` performs the steps outlined in the section above using the two `builder`s for the loader and app. +During normal single-image builds, the `targetBuilder` initializes and builds the application +`builder`. During the split image build, the `targetBuilder` performs the steps outlined in the +section above using the two `builder`s for the loader and app. Special symbol and link features are designed as follows: * Newt uses objdump to parse the symbol maps in the `.a` and `.elf` files. -* Newt uses the `--undefined=` option of the linker to force the loader to keep symbols used by the app (but not used by the linker) +* Newt uses the `--undefined=` option of the linker to force the loader to keep symbols used by +the app (but not used by the linker) * Newt uses objcopy with the `-K` (keep) option when building the special linker `.elf`. * Newt uses the `--just-symbols` option of the linker to link against the loader `.elf` file. #### newt create-image -`create-image` uses two different methods to compute the image hash for standard and split images. For split images, the hash is computed starting with the 32-byte hash of the loader, then continuing with the hashing algorithm used by the standard application. This ensures that the split app can be "validated" against a loader image specifically. +`create-image` uses two different methods to compute the image hash for standard and split images. +For split images, the hash is computed starting with the 32-byte hash of the loader, then continuing +with the hashing algorithm used by the standard application. This ensures that the split app can be "validated" against a loader image specifically. #### newt errors Newt has several new build errors when building split images. -* Linker script undefined. If the BSP for your application does not define a split image linker script the build will fail. +* Linker script undefined. If the BSP for your application does not define a split image linker script +the build will fail. -If newt finds that the same library (for example libs/os) has a different implementaiton in the loader and app, it will generate an error and fail to build. These differences can arise when `#ifdef` or features are included in one app and not the other. For example, it the loader includes `libs/console/stubs` and the app includes `libs/console/full` this may change implementations of certain functions within other packages. +If newt finds that the same library (for example libs/os) has a different implementaiton in the loader +and app, it will generate an error and fail to build. These differences can arise when `#ifdef` or features +are included in one app and not the other. For example, it the loader includes `libs/console/stubs` and the +app includes `libs/console/full` this may change implementations of certain functions within other packages. ### Image manifest @@ -156,15 +195,18 @@ newt builds a single manifest for split images, adding extra tags to the manifes ] ``` -The manifest lists packages in both the loader and app. The app package list only contains those packages that reside in the app image itself. +The manifest lists packages in both the loader and app. The app package list only contains those +packages that reside in the app image itself. ### libs/bootutil -Bootutil has been expanded to include a function that looks for a split app image in slot 2, verifies that it matches the loader image in slot 1 and then fetches the entry information for the split app. +Bootutil has been expanded to include a function that looks for a split app image in slot 2, verifies +that it matches the loader image in slot 1 and then fetches the entry information for the split app. ### libs/split -A small split image library was created to provide newtmgr commands for split image and to hold the configuration for split image. See newtmgr below for details. +A small split image library was created to provide newtmgr commands for split image and to hold the +configuration for split image. See newtmgr below for details. It also contains the function used by a loader to validate and boot a split image. @@ -180,17 +222,23 @@ A sample app that can be built as a split image with slinky. A BSP needs additional components to be "split image ready". -The split image requires a special linker script. The split image needs to run from the second image partition (since it's using the loader library that is linked to be placed in the first partition). It needs to reserve space for RAM used by the loader. It also does not need to include the vector table (just a bit of it). +The split image requires a special linker script. The split image needs to run from the second image +partition (since it's using the loader library that is linked to be placed in the first partition). +It needs to reserve space for RAM used by the loader. It also does not need to include the vector table (just a bit of it). -The startup of the split image is different than a typical image. It needs to copy `.data` from the loader image, and zero the loader image bss. For this, it must reference symbols defined in the linker script of the loader. It has a special entry symbol that differentiates it from the entry symbol in the loader application. +The startup of the split image is different than a typical image. It needs to copy `.data` from the +loader image, and zero the loader image bss. For this, it must reference symbols defined in the linker +script of the loader. It has a special entry symbol that differentiates it from the entry symbol in the +loader application. -Several of the bsp scripts need to handle additional agruments to deal with the two images produced by newt when building split images - mainly download and debug. +Several of the bsp scripts need to handle additional agruments to deal with the two images produced +by newt when building split images - mainly download and debug. Add the following components to enable your BSP for split images: 1. A split image linker file 2. A startup file for the split image -3. A property in the pkg.yml file to tell newt what linker script to use for partition 2 images. The property is defined as `pkg.part2linkerscript: "split-nrf52dk.ld` for example. +3. A property in the pkg.yml file to tell newt what linker script to use for partition 2 images. The property is defined as `pkg.part2linkerscript: "split-nrf52dk.ld` for example. 4. Modified download script 5. Modified sbrk functionality @@ -202,7 +250,7 @@ The split image linker script must have the following. The split linker must be linked to run from the second flash image slot. For example: -``` +```c MEMORY { FLASH (rx) : ORIGIN = 0x00042000, LENGTH = 0x3a000 @@ -212,11 +260,13 @@ MEMORY The split linker must define the entry symbol as Reset_Handler_split. For example: -``` +```c ENTRY(Reset_Handler_split) ``` -The split linker must define the first two words in the vector table (initial SP and Reset Vector). The additional vector entries are part of the loader and are not needed in the split image. The bootloader accesses these entries at the beginning of the image slot (first 2 words). For example: +The split linker must define the first two words in the vector table (initial SP and Reset Vector). The additional +vector entries are part of the loader and are not needed in the split image. The bootloader accesses these +entries at the beginning of the image slot (first 2 words). For example: ``` .text : @@ -224,10 +274,15 @@ The split linker must define the first two words in the vector table (initial SP __split_isr_vector_start = .; KEEP(*(.isr_vector_split)) __split_isr_vector_end = .; - ... + ... + } ``` -The split linker must ensure that it doesn't overwrite the BSS and DATA sections of the loader (they are both using RAM). Note, the two apps don't run at the same time, but the loader has global data that its libraries use. This cannot be overwritten by the application. An example linker section that accomplishes this can be found in `/hw/bsp/nrf52dk/split-nrf52dk.ld`. When linking against the loader, the loader exports the following symbosl which can be used by the split app code: +The split linker must ensure that it doesn't overwrite the BSS and DATA sections of the loader (they are +both using RAM). Note, the two apps don't run at the same time, but the loader has global data that its +libraries use. This cannot be overwritten by the application. An example linker section that accomplishes +this can be found in `/hw/bsp/nrf52dk/split-nrf52dk.ld`. When linking against the loader, the loader exports +the following symbosl which can be used by the split app code: * `__HeapBase_loader` * `__bss_start___loader` @@ -238,7 +293,7 @@ The split linker must ensure that it doesn't overwrite the BSS and DATA sections The split app linker can use `__HeapBase_loader` to skip RAM used by the loader as follows. -``` +```c /* save RAM used by the split image. This assumes that * the loader uses all the RAM up to its HeapBase */ .loader_ram_contents : @@ -253,36 +308,44 @@ The split app linker can use `__HeapBase_loader` to skip RAM used by the loader ### split image startup code -The split application needs separate startup code to intialize the split image before running main. THe split image is specially linked so that _start and main are included individually for the loader and split app. +The split application needs separate startup code to intialize the split image before running main. The +split image is specially linked so that `_start` and `main` are included individually for the loader and split app. The split app startup code must have the following. 1. A definition of the split image vector table (first two words). 2. The entry point function to start the code `Reset_Handler_split` -3. Code that copies the .data section for the loader from Flash to RAM -4. Code that zeros the .bss section for the loader. -5. Code that calls _sbrkInit to set the heap pointers for the application (see below) +3. Code that copies the `.data` section for the loader from Flash to RAM +4. Code that zeros the `.bss` section for the loader. +5. Code that calls `_sbrkInit` to set the heap pointers for the application (see below) 6. Code that calls the `bsp_slot_init_split_application` function (see below) An example can be found in the `/hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52_split.s` ### Download script -The download script needs to be modified to include support for passing the image slot number in the build. Image slots are referenced as 0 and 1. Loading bootloaders ignore the image slot numbers. +The download script needs to be modified to include support for passing the image slot number in the build. +Image slots are referenced as 0 and 1. Loading bootloaders ignore the image slot numbers. See and example in `/hw/bsp/bmd300eval/bmd300eval_download.sh`. ### Sbrk functionality -Split image (either a loader or app) references a single set of heap managment functions. But the heap location and size is different depending which image is running. Special functionality is needed to handle the dynamic setting of the heap base and limit. +Split image (either a loader or app) references a single set of heap managment functions. But the heap location and +size is different depending which image is running. Special functionality is needed to handle the dynamic +setting of the heap base and limit. -Instead of hard-coding the heap base and limit at link time (depending on the size of data and bss), sbrk needs to be dynamically initialized with these values from the startup code. +Instead of hard-coding the heap base and limit at link time (depending on the size of data and bss), sbrk +needs to be dynamically initialized with these values from the startup code. -See an example in `/hw/bsp/bmd300eval/src/sbrk.c` in the core repository. The function `_sbrkInit` must be called from the startup code of the split image and normal image startup code with the appropriate values of heap base and limit. +See an example in `/hw/bsp/bmd300eval/src/sbrk.c` in the core repository. The function `_sbrkInit` must be +called from the startup code of the split image and normal image startup code with the appropriate +values of heap base and limit. ### Slot Init -A global variable tells mynewt whether the split image is runnning as just a stand-alone loader, or as the combined loader/app image. Its the responsibility of the startup code to set this global variable. +A global variable tells Mynewt whether the split image is runnning as just a stand-alone loader, or as +the combined loader/app image. Its the responsibility of the startup code to set this global variable. See `hw/bsp/bmd300eval/src/os_bsp.c` for and implementation of the functionality. @@ -304,15 +367,19 @@ Images: hash=1697bd1658f7e902e0191094c5f729446c9dd790c00a58e2bb37f56d6fcb72fe ``` -The bootloader is unable to boot split app images (of course it can boot the loader images), so do not use the `boot2` command to instruct mynewt to boot slot 2. +The bootloader is unable to boot split app images (of course it can boot the loader images), so do not use the `boot2` +command to instruct mynewt to boot slot 2. -Instead, use the new `split status` command to see the status of split images and to set their boot status. The split status command with no arguments returns status of the split image. The Split Value tells the loader how to boot the split app. Options are: +Instead, use the new `split status` command to see the status of split images and to set their boot status. +The split status command with no arguments returns status of the split image. The Split Value tells the loader +how to boot the split app. Options are: * `none` Don't boot the split application. Just remain running in the loader. * `test` Boot the split application, but revert back to the loader on the next reset. * `run` Boot the split application. -The split status command also verified the hash of the split application (using the hash of the loader as shown above) and returns the status of the check (matching or non-matching). +The split status command also verified the hash of the split application (using the hash of the loader +as shown above) and returns the status of the check (matching or non-matching). ``` newtmgr -c connection split status @@ -320,7 +387,8 @@ newtmgr -c connection split status Split status is matching ``` -When the split image application is running, the active hash in the boot2 command will match the hash of the split application (in slot 2). For example: +When the split image application is running, the active hash in the `boot2` command will match the +hash of the split application (in slot 2). For example: ``` prompt$ newtmgr -c foo1 image boot @@ -333,7 +401,8 @@ prompt$ newtmgr -c foo1 image boot When running via newt, the `newt load` command will load both parts of a split image, the loader and application. -When running via newtmgr a sequence of commands is required to upgrade. Assuming you are running the split app in `run` mode the following sequence will upgrade +When running via newtmgr a sequence of commands is required to upgrade. Assuming you are running the +split app in `run` mode the following sequence will upgrade 1. newtmgr split status none 2. newtmgr reboot
