mirror of
https://github.com/espressif/openthread.git
synced 2026-08-06 10:47:46 +00:00
[devsite] migrate Porting guide to GitHub (#5936)
This commit is contained in:
Jeff Bumgardner
@@ -0,0 +1,20 @@
|
||||
toc:
|
||||
- title: Overview
|
||||
path: /guides/porting/
|
||||
step_group: porting_guide
|
||||
- title: Set up the Build Environment
|
||||
path: /guides/porting/set-up-the-build-environment
|
||||
step_group: porting_guide
|
||||
- title: Implement Platform Abstraction Layer APIs
|
||||
path: /guides/porting/implement-platform-abstraction-layer-apis
|
||||
step_group: porting_guide
|
||||
- title: Implement Advanced Features
|
||||
path: /guides/porting/implement-advanced-features
|
||||
step_group: porting_guide
|
||||
- title: Validate the Port
|
||||
path: /guides/porting/validate-the-port
|
||||
step_group: porting_guide
|
||||
- title: Certification and README
|
||||
path: /guides/porting/certification-and-readme
|
||||
step_group: porting_guide
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
# Certification and README
|
||||
|
||||
## Thread Certification
|
||||
|
||||
To achieve Thread Certification, the port must be tested against the official
|
||||
[Thread Harness](http://graniteriverlabs.com/thread/) and pass all scenarios
|
||||
listed in the Thread Certification Test Plan.
|
||||
|
||||
For more information, see
|
||||
[Certification](https://openthread.io/certification).
|
||||
|
||||
## README
|
||||
|
||||
A detailed README is necessary to demonstrate how to build and run OpenThread on
|
||||
a new hardware platform.
|
||||
|
||||
At a minimum, the README should include:
|
||||
|
||||
- Information about the hardware platform
|
||||
- Links to the required toolchain
|
||||
- How to configure platform-specific vendor software
|
||||
- How to build and flash binaries onto the platform
|
||||
- Versions of libraries and toolchains used for validation of the port
|
||||
|
||||
See the
|
||||
[EFR32MG12 README](https://github.com/openthread/openthread/blob/master/examples/platforms/efr32/efr32mg12/README.md)
|
||||
for an example.
|
||||
@@ -0,0 +1,135 @@
|
||||
# Implement Advanced Features
|
||||
|
||||
Some advanced features are optional, depending on whether or not they are
|
||||
supported on the target hardware platform.
|
||||
|
||||
<a id="auto-frame-pending"></a>
|
||||
|
||||
## Step 1: Auto frame pending
|
||||
|
||||
IEEE 802.15.4 defines two kinds of data transmission methods between parent and
|
||||
child: direct transmission and indirect transmission. The latter is designed
|
||||
primarily for sleepy end devices (SEDs) which sleep most of the time,
|
||||
periodically waking to poll the parent for queued data.
|
||||
|
||||
- **Direct Transmission** — parent sends a data frame directly to the end device
|
||||
<img src="/guides/images/ot-auto-frame-direct.png" srcset="/guides/images/ot-auto-frame-direct.png 1x, /guides/images/ot-auto-frame-direct_2x.png 2x" border="0" alt="Direct Transmission" width="400" />
|
||||
|
||||
- **Indirect Transmission** — parent holds data until requested by its intended end device
|
||||
<img src="/guides/images/ot-auto-frame-indirect.png" srcset="/guides/images/ot-auto-frame-indirect.png 1x, /guides/images/ot-auto-frame-indirect_2x.png 2x" border="0" alt="Direct Transmission" width="400" />
|
||||
|
||||
In the Indirect case, a child end device must first poll the parent to determine
|
||||
whether any data is available for it. To do this, the child sends a data
|
||||
request, which the parent acknowledges. The parent then determines whether it
|
||||
has any data for the child device; if so, it sends a data packet to the child
|
||||
device, which acknowledges receipt of the data.
|
||||
|
||||
If the radio supports dynamically setting the Frame Pending bit in outgoing
|
||||
acknowledgments to SEDs, the drivers must implement the
|
||||
[source address match](https://github.com/openthread/openthread/blob/master/include/openthread/platform/radio.h#L288)
|
||||
API to enable this capability. OpenThread uses this API to tell the radio which
|
||||
SEDs to set the Frame Pending bit for.
|
||||
|
||||
If the radio does not support dynamically setting the Frame Pending bit, the
|
||||
radio might stub out the source address match API to return
|
||||
`OT_ERROR_NOT_IMPLEMENTED`.
|
||||
|
||||
## Step 2: Energy Scan/Detect with radio
|
||||
|
||||
> Note: This feature is optional.
|
||||
|
||||
The Energy Scan/Detect feature requires the radio chip to sample energy
|
||||
presenting on selected channels and return the detected energy value to the
|
||||
upper layer.
|
||||
|
||||
If this feature is not implemented, the IEEE 802.15.4 MAC layer
|
||||
sends/receives a Beacon Request/Response packet to evaluate the current
|
||||
energy value on the channel.
|
||||
|
||||
If the radio chip supports Energy Scan/Detect, make sure to disable software
|
||||
energy scanning logic by setting the macro
|
||||
`OPENTHREAD_CONFIG_ENABLE_SOFTWARE_ENERGY_SCAN = 0`.
|
||||
|
||||
## Step 3: Hardware acceleration for mbedTLS
|
||||
|
||||
> Note: This feature is optional.
|
||||
|
||||
mbedTLS defines several macros in the main configuration header file,
|
||||
[`mbedtls-config.h`](https://github.com/openthread/openthread/blob/master/third_party/mbedtls/mbedtls-config.h),
|
||||
to allow users to enable alternative implementations of AES, SHA1, SHA2, and
|
||||
other modules, as well as individual functions for the Elliptic curve
|
||||
cryptography (ECC) over GF(p) module. See
|
||||
[mbedTLS hardware acceleration](https://docs.mbed.com/docs/mbed-os-handbook/en/latest/advanced/tls_hardware_acceleration/)
|
||||
for more information.
|
||||
|
||||
OpenThread does not enable those macros, therefore the symmetric crypto
|
||||
algorithms, hash algorithms and ECC functions all utilize software
|
||||
implementations by default. These implementations require considerable memory
|
||||
and computational resources. For optimal performance and a better user
|
||||
experience, we recommend enabling hardware acceleration instead of software to
|
||||
implement the above operations.
|
||||
|
||||
To enable hardware acceleration within OpenThread, the following mbedTLS
|
||||
configuration header files should be added to the compile option flags in the
|
||||
platform example's Makefile:
|
||||
|
||||
- Main configuration, which defines all necessary macros used in OpenThread:
|
||||
`/openthread/third-party/mbedtls/mbedtls-config.h`
|
||||
- User-specific configuration, which defines alternate implementations of
|
||||
modules and functions: `/openthread/examples/platforms/{platform-name}/crypto/{platform-name}-mbedtls-config.h`
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
EFR32_MBEDTLS_CPPFLAGS = -DMBEDTLS_CONFIG_FILE='\"mbedtls-config.h\"'
|
||||
EFR32_MBEDTLS_CPPFLAGS += -DMBEDTLS_USER_CONFIG_FILE='\"efr32-mbedtls-config.h\"'
|
||||
```
|
||||
|
||||
Commented macros in `mbedtls-config.h` are not mandatory, and can be enabled in
|
||||
the user-specific configuration header file for hardware acceleration.
|
||||
|
||||
For a complete example user-specific configuration, see the
|
||||
[`mbedtls_config_autogen.h`](https://github.com/openthread/openthread/blob/master/examples/platforms/efr32/efr32mg12/crypto/mbedtls_config_autogen.h)
|
||||
file.
|
||||
|
||||
### AES module
|
||||
|
||||
OpenThread Security applies AES CCM (Counter with CBC-MAC) crypto to
|
||||
encrypt/decrypt the IEEE 802.15.4 or MLE messages and validates the message
|
||||
integration code. Hardware acceleration should at least support basic AES ECB
|
||||
(Electronic Codebook Book) mode for AES CCM basic functional call.
|
||||
|
||||
To utilize an alternative AES module implementation:
|
||||
|
||||
1. Define the `MBEDTLS_AES_ALT` macro in the user-specific mbedTLS
|
||||
configuration header file
|
||||
1. Indicate the path of the `aes_alt.h` file using the `MBEDTLS_CPPFLAGS`
|
||||
variable
|
||||
|
||||
### SHA256 module
|
||||
|
||||
OpenThread Security applies HMAC and SHA256 hash algorithms to calculate the
|
||||
hash value for master key management and PSKc generation according to the Thread
|
||||
Specification.
|
||||
|
||||
To utilize an alternative basic SHA256 module implementation:
|
||||
|
||||
1. Define the `MBEDTLS_SHA256_ALT` macro in the user-specific mbedTLS
|
||||
configuration header file
|
||||
1. Indicate the path of the `sha256_alt.h` file using the `MBEDTLS_CPPFLAGS`
|
||||
variable
|
||||
|
||||
### ECC functions
|
||||
|
||||
Since mbedTLS currently only supports hardware acceleration for parts of ECC
|
||||
functions, rather than the entire module, you can choose to implement some
|
||||
functions defined in
|
||||
`{path-to-mbedtls}/library/ecp.c` to accelerate ECC
|
||||
point multiplication.
|
||||
|
||||
Curve secp256r1 is used in the key exchange algorithm of the
|
||||
[ECJPAKE](https://tools.ietf.org/html/draft-cragie-tls-ecjpake-00) draft. Hence,
|
||||
hardware acceleration should at least support the secp256r1 short weierstrass
|
||||
curve operation. See [SiLabs CRYPTO Hardware Acceleration for
|
||||
mbedTLS](https://siliconlabs.github.io/Gecko_SDK_Doc/mbedtls/html/group__sl__crypto.html)
|
||||
for an example.
|
||||
@@ -0,0 +1,204 @@
|
||||
# Implement Platform Abstraction Layer APIs
|
||||
|
||||
OpenThread is OS and platform agnostic, with a narrow Platform Abstraction Layer
|
||||
(PAL). This PAL defines:
|
||||
|
||||
<figure class="attempt-right">
|
||||
<img src="/guides/images/ot-arch-porting.png" srcset="/guides/images/ot-arch-porting.png 1x, /guides/images/ot-arch-porting_2x.png 2x" border="0" alt="Porting Architecture" />
|
||||
</figure>
|
||||
|
||||
- Alarm interface for free-running timer with alarm
|
||||
- Bus interfaces (UART, SPI) for communicating CLI and Spinel messages
|
||||
- Radio interface for IEEE 802.15.4-2006 communication
|
||||
- GCC-specific initialization routines
|
||||
- Entropy for true random number generation
|
||||
- Settings service for non-volatile configuration storage
|
||||
- Logging interface for delivering OpenThread log messages
|
||||
- System-specific initialization routines
|
||||
|
||||
All APIs should be implemented based on the underlying Hardware Abstraction
|
||||
Layer (HAL) Build Support Package (BSP).
|
||||
|
||||
> Key Point: Unless noted as optional, **Platform Abstraction Layer APIs are
|
||||
mandatory** and must be implemented according to the definitions in each API
|
||||
header file.
|
||||
|
||||
API files should be placed in the following directories:
|
||||
|
||||
Type | Directory
|
||||
------|------
|
||||
Platform-specific PAL implementation | `/openthread/examples/platforms/{platform-name}`
|
||||
Header files — Non-volatile storage API | `/openthread/examples/platforms/utils`
|
||||
All other header files | `/openthread/include/openthread/platform`
|
||||
HAL BSP | `/openthread/third_party/{platform-name}`
|
||||
|
||||
## Step 1: Alarm
|
||||
|
||||
API declaration:
|
||||
|
||||
[`/openthread/include/openthread/platform/alarm-milli.h`](https://github.com/openthread/openthread/blob/master/include/openthread/platform/alarm-milli.h)
|
||||
|
||||
The Alarm API provides fundamental timing and alarm services for the upper layer
|
||||
timer implementation.
|
||||
|
||||
There are two alarm service types,
|
||||
[millisecond](https://github.com/openthread/openthread/blob/master/include/openthread/platform/alarm-milli.h)
|
||||
and [microsecond](https://github.com/openthread/openthread/blob/master/include/openthread/platform/alarm-micro.h).
|
||||
Millisecond is required for a new hardware platform. Microsecond is optional.
|
||||
|
||||
## Step 2: UART
|
||||
|
||||
> Note: This API is optional.
|
||||
|
||||
API declaration:
|
||||
|
||||
[`/openthread/include/openthread/platform/uart.h`](https://github.com/openthread/openthread/blob/master/include/openthread/platform/uart.h)
|
||||
|
||||
The UART API implements fundamental serial port communication via the UART
|
||||
interface.
|
||||
|
||||
While the OpenThread
|
||||
[CLI](https://github.com/openthread/openthread/tree/master/examples/apps/cli)
|
||||
and [NCP](https://github.com/openthread/openthread/tree/master/examples/apps/ncp)
|
||||
add-ons depend on the UART interface to interact with the host side, UART API
|
||||
support is optional. However, even if you do not plan to use these add-ons on
|
||||
your new hardware platform example, we highly recommend you add support for a
|
||||
few reasons:
|
||||
|
||||
- The CLI is useful for validating that the port works correctly
|
||||
- The Harness Automation Tool uses the UART interface to control OpenThread for testing and certification purposes
|
||||
|
||||
If the target hardware platform supports a USB CDC module rather than UART, make
|
||||
sure to:
|
||||
|
||||
- Install the correct USB CDC driver on the host side
|
||||
- Replace the UART API implementation with the USB CDC driver (along with BSP)
|
||||
on the OpenThread side, using the same function prototypes
|
||||
|
||||
## Step 3: Radio
|
||||
|
||||
API declaration:
|
||||
|
||||
[`/openthread/include/openthread/platform/radio.h`](https://github.com/openthread/openthread/blob/master/include/openthread/platform/radio.h)
|
||||
|
||||
The Radio API defines all necessary functions called by the upper IEEE 802.15.4
|
||||
MAC layer. The Radio chip must be fully compliant with the 2.4GHz IEEE
|
||||
802.15.4-2006 specification.
|
||||
|
||||
Due to its enhanced low power feature, OpenThread requires all platforms to
|
||||
implement auto frame pending (indirect transmission) by default, and the source
|
||||
address match table should also be implemented in the `radio.h` source file.
|
||||
|
||||
However, if your new hardware platform example is resource limited, the source
|
||||
address table can be defined as zero length. See
|
||||
[Auto Frame Pending](#auto-frame-pending) for more information.
|
||||
|
||||
> Note: The `otPlatRadioGetIeeeEui64` Radio API **MUST** return a unique
|
||||
administered factory-assigned IEEE EUI-64 that includes the manufacturer's OUI.
|
||||
The EUI-64 is used to match to steering data during the Joiner Discovery phase.
|
||||
|
||||
## Step 4: Misc/Reset
|
||||
|
||||
API declaration:
|
||||
|
||||
[`/openthread/include/openthread/platform/misc.h`](https://github.com/openthread/openthread/blob/master/include/openthread/platform/misc.h)
|
||||
|
||||
The Misc/Reset API provides a method to reset the software on the chip, and
|
||||
query the reason for last reset.
|
||||
|
||||
## Step 5: Entropy
|
||||
|
||||
> Note: **Implementation of this API is required in every port of OpenThread.**
|
||||
|
||||
API declaration:
|
||||
|
||||
[`/openthread/include/openthread/platform/entropy.h`](https://github.com/openthread/openthread/blob/master/include/openthread/platform/entropy.h)
|
||||
|
||||
The Entropy API provides a true random number generator (TRNG) for the upper
|
||||
layer, which is used to maintain security assets for the entire OpenThread
|
||||
network. The API should guarantee that a new random number is generated for
|
||||
each function call. Security assets affected by the TRNG include:
|
||||
|
||||
- AES CCM nonce
|
||||
- Random delayed jitter
|
||||
- Devices' extended address
|
||||
- The initial random period in the trickle timer
|
||||
- CoAP token/message IDs
|
||||
|
||||
Note that many platforms have already integrated a random number generator,
|
||||
exposing the API in its BSP package. In the event that the target hardware
|
||||
platform does not support TRNG, consider leveraging ADC module sampling to
|
||||
generate a fixed-length random number. Sample over multiple iterations if
|
||||
necessary to meet the TRNG requirements (uint32_t).
|
||||
|
||||
When the macro `MBEDTLS_ENTROPY_HARDWARE_ALT` is set to `1`, this API should
|
||||
also provide a method to generate the hardware entropy used in the mbedTLS
|
||||
library.
|
||||
|
||||
## Step 6: Non-volatile storage
|
||||
|
||||
> Note: **Only _one_ of these APIs is required to be implemented in every port
|
||||
of OpenThread.**
|
||||
|
||||
API declarations:
|
||||
|
||||
[`/openthread/include/openthread/platform/flash.h`](https://github.com/openthread/openthread/blob/master/include/openthread/platform/flash.h)
|
||||
|
||||
**or**
|
||||
|
||||
[`/openthread/include/openthread/platform/settings.h`](https://github.com/openthread/openthread/blob/master/include/openthread/platform/settings.h)
|
||||
|
||||
The Non-volatile storage requirement can be satisfied by implementing one of the
|
||||
two APIs listed above. The Flash API implements a flash storage driver, while
|
||||
the Settings API provides functions for an underlying flash operation
|
||||
implementation to the upper layer.
|
||||
|
||||
These APIs expose to the upper layer:
|
||||
|
||||
- The available non-volatile storage size used to store application data (for
|
||||
example, active/pending operational dataset, current network parameters and
|
||||
thread devices' credentials for reattachment after reset)
|
||||
- Read, write, erase, and query flash status operations
|
||||
|
||||
Use `OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE` in your platform example's
|
||||
core config file to indicate which API the platform should use. If set to `1`,
|
||||
the Flash API must be implemented. Otherwise, the Settings API must be
|
||||
implemented.
|
||||
|
||||
This flag must be set in your
|
||||
`/openthread/examples/platforms/{platform-name}/openthread-core-{platform-name}-config.h`
|
||||
file.
|
||||
|
||||
## Step 7: Logging
|
||||
|
||||
> Note: This API is optional.
|
||||
|
||||
API declaration:
|
||||
|
||||
[`/openthread/include/openthread/platform/logging.h`](https://github.com/openthread/openthread/blob/master/include/openthread/platform/logging.h)
|
||||
|
||||
The Logging API implements OpenThread's logging and debug functionality, with
|
||||
multiple levels of debug output available. This API is optional if you do not
|
||||
plan to utilize OpenThread's logging on your new hardware platform example.
|
||||
|
||||
The highest and most detailed level is `OPENTHREAD_LOG_LEVEL_DEBG`, which
|
||||
prints all raw packet information and logs lines through the serial port or on
|
||||
the terminal. Choose a debug level that best meets your needs.
|
||||
|
||||
## Step 8: System-specific
|
||||
|
||||
API declaration:
|
||||
|
||||
[`/openthread/examples/platforms/openthread-system.h`](https://github.com/openthread/openthread/blob/master/examples/platforms/openthread-system.h)
|
||||
|
||||
The System-specific API primarily provides initialization and deinitialization
|
||||
operations for the selected hardware platform. This API is not called by the
|
||||
OpenThread library itself, but may be useful for your system/RTOS. You can also
|
||||
implement the initialization of other modules (for example, UART, Radio, Random,
|
||||
Misc/Reset) in this source file.
|
||||
|
||||
Implementation of this API depends on your use case. If you wish to use the
|
||||
generated [CLI and NCP applications](https://openthread.io/guides/build#binaries) for an [example
|
||||
platform](https://github.com/openthread/openthread/tree/master/examples/platforms),
|
||||
you must implement this API. Otherwise, any API can be implemented to integrate
|
||||
the example platform drivers into your system/RTOS.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Porting OpenThread to New Hardware Platforms
|
||||
|
||||
Porting the OpenThread stack to a new hardware platform consists of five steps:
|
||||
|
||||
1. [Set up the build environment](https://github.com/openthread/openthread/blob/master/doc/site/en/guides/porting/set-up-the-build-environment.md)
|
||||
1. [Implement Platform Abstraction Layer APIs](https://github.com/openthread/openthread/blob/master/doc/site/en/guides/porting/implement-platform-abstraction-layer-apis.md)
|
||||
1. [Implement advanced features (Hardware Abstraction Layer)](https://github.com/openthread/openthread/blob/master/doc/site/en/guides/porting/implement-advanced-features.md)
|
||||
1. [Validate the port](https://github.com/openthread/openthread/blob/master/doc/site/en/guides/porting/validate-the-port.md)
|
||||
1. [Certification and README](https://github.com/openthread/openthread/blob/master/doc/site/en/guides/porting/certification-and-readme.md)
|
||||
|
||||
## Hardware platform requirements
|
||||
|
||||
OpenThread requires the following platform services:
|
||||
|
||||
- [IEEE 802.15.4-2006](https://standards.ieee.org/findstds/standard/802.15.4-2006.html)
|
||||
2.4 GHz radio
|
||||
- Send and receive IEEE 802.15.4 frames
|
||||
- Generate IEEE 802.15.4 Acknowledgment frames
|
||||
- Provide Received Signal Strength Indicator (RSSI) measurements on
|
||||
received frames
|
||||
- A millisecond-resolution free-running timer with alarm
|
||||
- Non-volatile storage for storing network configuration settings
|
||||
- A true random number generator (TRNG)
|
||||
|
||||
## Example builds
|
||||
|
||||
Several example builds are provided in the OpenThread repository. For more
|
||||
information, see [Platforms](https://openthread.io/platforms).
|
||||
|
||||
For a complete end-to-end example of how to port OpenThread from scratch, see
|
||||
the [Add support for EFR32](https://github.com/openthread/openthread/pull/1592)
|
||||
pull request.
|
||||
|
||||
@@ -0,0 +1,217 @@
|
||||
# Set Up the Build Environment
|
||||
|
||||
To promote free and open development, OpenThread uses GNU Autotools in the build
|
||||
toolchain. Currently, this toolchain is required for porting OpenThread to a new
|
||||
hardware platform.
|
||||
|
||||
Other build toolchains might be supported in the future, but they are not within
|
||||
the scope of this porting guide.
|
||||
|
||||
> Note: For all path and code examples in this porting
|
||||
guide, always replace {platform-name} with the name of
|
||||
your new platform example. Most of the examples in the guide use a `efr32` platform
|
||||
name.
|
||||
|
||||
## Step 1: GNU Autoconf
|
||||
|
||||
The [Autoconf](https://www.gnu.org/software/autoconf/autoconf.html) script
|
||||
contains the basic system configuration options, including specific
|
||||
platform-relative macro definitions. These macros can be exposed for
|
||||
conditional compilation in other Makefiles during the pre-compiling phase.
|
||||
|
||||
The OpenThread Autoconf script is located at:
|
||||
[`/openthread/configure.ac`](https://github.com/openthread/openthread/blob/master/configure.ac)
|
||||
|
||||
### Platform example name
|
||||
|
||||
In the `AC_ARG_WITH(examples ...)` macro, add the new hardware platform example name. The name
|
||||
should be added in alphabetical order.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
AC_ARG_WITH(examples,
|
||||
[AS_HELP_STRING([--with-examples=TARGET],
|
||||
[Specify the examples from one of: none, simulation, cc2538, cc2650, efr32, nrf52840 @<:@default=none@:>@.])],
|
||||
[
|
||||
case "${with_examples}" in
|
||||
none)
|
||||
;;
|
||||
simulation|cc2538|cc2650|efr32|nrf52840)
|
||||
if test ${enable_posix_app} = "yes"; then
|
||||
AC_MSG_ERROR([--with-examples must be none when POSIX apps are enabled by --enable-posix-app])
|
||||
fi
|
||||
;;
|
||||
*)
|
||||
AC_MSG_ERROR([Invalid value ${with_examples} for --with-examples])
|
||||
;;
|
||||
esac
|
||||
],
|
||||
[with_examples=none])
|
||||
```
|
||||
|
||||
### Platform-specific C preprocessor symbol
|
||||
|
||||
Define a platform-specific C preprocessor symbol for the platform example and
|
||||
expose it.
|
||||
|
||||
The platform-specific C preprocessor symbol is exposed at
|
||||
`include/openthread-config.h`. By including the symbol in this header file, we
|
||||
can leverage it in our source code for preprocessor conditional compilation
|
||||
cases.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
case ${with_examples} in
|
||||
|
||||
...
|
||||
|
||||
efr32)
|
||||
OPENTHREAD_EXAMPLES_EFR32=1
|
||||
AC_DEFINE_UNQUOTED([OPENTHREAD_EXAMPLES_EFR32],[${OPENTHREAD_EXAMPLES_EFR32}],[Define to 1 if you want to use efr32 examples])
|
||||
;;
|
||||
|
||||
...
|
||||
|
||||
esac
|
||||
|
||||
...
|
||||
|
||||
AC_SUBST(OPENTHREAD_EXAMPLES_EFR32)
|
||||
AM_CONDITIONAL([OPENTHREAD_EXAMPLES_EFR32], [test "${OPENTHREAD_EXAMPLES}" = "efr32"])
|
||||
```
|
||||
|
||||
### Makefile output directory
|
||||
|
||||
In the `AC_CONFIG_FILES` macro, add a Makefile output directory for the
|
||||
platform example.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
AC_CONFIG_FILES ([
|
||||
examples/platforms/efr32/Makefile
|
||||
])
|
||||
```
|
||||
|
||||
## Step 2: GNU Automake
|
||||
|
||||
Create and modify [Automake](https://www.gnu.org/software/automake/) files to
|
||||
support the new platform example.
|
||||
|
||||
The following platform-specific Automake files need to be created:
|
||||
|
||||
- `/openthread/examples/Makefile-{platform-name}`
|
||||
- `/openthread/examples/platforms/{platform-name}/Makefile.am`
|
||||
- `/openthread/examples/platforms/{platform-name}/Makefile.platform.am`
|
||||
|
||||
See [`/examples`](https://github.com/openthread/openthread/tree/master/examples/) for sample implementations of
|
||||
these files.
|
||||
|
||||
The following Automake files also need to be updated with your platform
|
||||
information:
|
||||
|
||||
- [`/openthread/examples/platforms/Makefile.am`](https://github.com/openthread/openthread/blob/master/examples/platforms/Makefile.am)
|
||||
- [`/openthread/examples/platforms/Makefile.platform.am`](https://github.com/openthread/openthread/blob/master/examples/platforms/Makefile.platform.am)
|
||||
|
||||
### Linker script configuration
|
||||
|
||||
The [GNU Linker](http://www.ece.ufrgs.br/~fetter/eng04476/manuals/ld.pdf) script
|
||||
describes how to map all sections in the input files (`.o` "object" files
|
||||
generated by the GNU Compiler Collection (GCC)) to the final output file (for
|
||||
example, `.elf`). It also determines the storage location of each segment of an
|
||||
executable program, as well as the entry address. The platform-specific linker
|
||||
script is often provided with the platform's BSP.
|
||||
|
||||
Configure the `ld` tool to point to the platform-specific linker script using
|
||||
the `-T` option of the `LDADD_COMMON` variable.
|
||||
|
||||
Create
|
||||
`/openthread/examples/platforms/{platform-name}/Makefile.platform.am`
|
||||
and point the new platform to its linker script:
|
||||
|
||||
```
|
||||
if OPENTHREAD_EXAMPLES_EFR32
|
||||
LDADD_COMMON += \
|
||||
$(top_builddir)/examples/platforms/efr32/libopenthread-efr32.a \
|
||||
$(top_srcdir)/third_party/silabs/gecko_sdk_suite/v1.0/platform/radio/rail_lib/autogen/librail_release/librail_efr32xg12_gcc_release.a \
|
||||
$(NULL)
|
||||
|
||||
LDFLAGS_COMMON += \
|
||||
-T $(top_srcdir)/third_party/silabs/gecko_sdk_suite/v1.0/platform/Device/SiliconLabs/EFR32MG12P/Source/GCC/efr32mg12p.ld \
|
||||
$(NULL)
|
||||
endif # OPENTHREAD_EXAMPLES_EFR32
|
||||
```
|
||||
|
||||
Add the platform's linker script configuration to the
|
||||
[`/openthread/examples/platforms/Makefile.platform.am`](https://github.com/openthread/openthread/blob/master/examples/platforms/Makefile.platform.am)
|
||||
utility Makefile:
|
||||
|
||||
```
|
||||
if OPENTHREAD_EXAMPLES_EFR32
|
||||
include $(top_srcdir)/examples/platforms/efr32/Makefile.platform.am
|
||||
endif
|
||||
```
|
||||
|
||||
### Subdirectory configuration
|
||||
|
||||
Modify [`/openthread/examples/platforms/Makefile.am`](https://github.com/openthread/openthread/blob/master/examples/platforms/Makefile.platform.am)
|
||||
to configure the package subdirectories for the new platform example.
|
||||
|
||||
Add the platform subdirectory name in the list for `make dist`, in alphabetical
|
||||
order:
|
||||
|
||||
```
|
||||
# Always package (e.g. for 'make dist') these subdirectories.
|
||||
|
||||
DIST_SUBDIRS = \
|
||||
cc2538 \
|
||||
cc2650 \
|
||||
efr32 \
|
||||
nrf52840 \
|
||||
simulation \
|
||||
utils \
|
||||
$(NULL)
|
||||
```
|
||||
|
||||
Append platform subdirectory name to the `SUBDIRS` variable:
|
||||
|
||||
```
|
||||
# Always build (e.g. for 'make all') these subdirectories.
|
||||
|
||||
if OPENTHREAD_EXAMPLES_EFR32
|
||||
SUBDIRS += efr32
|
||||
endif
|
||||
```
|
||||
|
||||
### Toolchain startup code
|
||||
|
||||
Toolchain startup code is often provided along with the platform's BSP. This
|
||||
code typically:
|
||||
|
||||
1. Implements the entry function (`Reset_Handler`) of the executable program
|
||||
1. Defines the interrupt vector table
|
||||
1. Initializes the Heap and Stack
|
||||
1. Copies the `.data` section from non-volatile memory to RAM
|
||||
1. Jumps to the application main function to execute the application logic
|
||||
|
||||
The startup code (C or assembly source code) must be added to the
|
||||
platform-specific `Makefile.am`, otherwise some key variables used in the linker
|
||||
script cannot be quoted correctly:
|
||||
|
||||
- `/openthread/examples/platforms/{platform-name}/Makefile.am`
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
libopenthread_efr32_a_SOURCES = \
|
||||
@top_builddir@/third_party/silabs/gecko_sdk_suite/v1.0/hardware/kit/common/bsp/bsp_bcc.c \
|
||||
@top_builddir@/third_party/silabs/gecko_sdk_suite/v1.0/hardware/kit/common/bsp/bsp_stk.c \
|
||||
@top_builddir@/third_party/silabs/gecko_sdk_suite/v1.0/platform/Device/SiliconLabs/EFR32MG12P/Source/system_efr32mg12p.c \
|
||||
@top_builddir@/third_party/silabs/gecko_sdk_suite/v1.0/platform/Device/SiliconLabs/EFR32MG12P/Source/GCC/startup_efr32mg12p.c \
|
||||
```
|
||||
|
||||
> Note: Any non-original derivative code (for example, linker script or
|
||||
toolchain startup code) must be contained in
|
||||
[`/openthread/third_party`](https://github.com/openthread/openthread/tree/master/third_party).
|
||||
@@ -0,0 +1,214 @@
|
||||
# Validate the Port
|
||||
|
||||
Basic validation is necessary to verify a successful port of OpenThread to a new
|
||||
hardware platform example.
|
||||
|
||||
## Step 1: Compile for the target platform
|
||||
|
||||
Demonstrate a successful build by compiling the example OpenThread application
|
||||
for the target platform.
|
||||
|
||||
```
|
||||
$ ./bootstrap
|
||||
$ make -f examples/Makefile-efr32 COMMISSIONER=1 JOINER=1
|
||||
```
|
||||
|
||||
## Step 2: Interact with the CLI
|
||||
|
||||
Demonstrate successful OpenThread execution and UART capability by interacting
|
||||
with the CLI.
|
||||
|
||||
Open a terminal to `/dev/ttyACM0` (serial port settings: 115200 8-N-1). Type
|
||||
`help` for a list of commands.
|
||||
|
||||
> Note: The set of CLI commands will vary based on the features enabled in a
|
||||
particular build. The majority of them have been elided in the example output
|
||||
below.
|
||||
|
||||
```
|
||||
> help
|
||||
help
|
||||
autostart
|
||||
bufferinfo
|
||||
...
|
||||
version
|
||||
whitelist
|
||||
```
|
||||
|
||||
## Step 3: Form a Thread network
|
||||
|
||||
Demonstrate successful protocol timers by forming a Thread network and verifying
|
||||
the node has transitioned to the Leader state.
|
||||
|
||||
```
|
||||
> dataset init new
|
||||
Done
|
||||
> dataset
|
||||
Active Timestamp: 1
|
||||
Channel: 13
|
||||
Channel Mask: 07fff800
|
||||
Ext PAN ID: d63e8e3e495ebbc3
|
||||
Mesh Local Prefix: fd3d:b50b:f96d:722d/64
|
||||
Master Key: dfd34f0f05cad978ec4e32b0413038ff
|
||||
Network Name: OpenThread-8f28
|
||||
PAN ID: 0x8f28
|
||||
PSKc: c23a76e98f1a6483639b1ac1271e2e27
|
||||
Security Policy: 0, onrcb
|
||||
Done
|
||||
> dataset commit active
|
||||
Done
|
||||
> ifconfig up
|
||||
Done
|
||||
> thread start
|
||||
Done
|
||||
```
|
||||
|
||||
Wait a couple of seconds...
|
||||
|
||||
```
|
||||
> state
|
||||
leader
|
||||
Done
|
||||
```
|
||||
|
||||
## Step 4: Attach a second node
|
||||
|
||||
Demonstrate successful radio communication by attaching a second node to the
|
||||
newly formed Thread network, using the same Thread Master Key and PAN ID from
|
||||
the first node:
|
||||
|
||||
```
|
||||
> dataset masterkey dfd34f0f05cad978ec4e32b0413038ff
|
||||
Done
|
||||
> dataset panid 0x8f28
|
||||
Done
|
||||
> dataset commit active
|
||||
Done
|
||||
> routerselectionjitter 1
|
||||
Done
|
||||
> ifconfig up
|
||||
Done
|
||||
> thread start
|
||||
Done
|
||||
```
|
||||
|
||||
Wait a couple of seconds...
|
||||
|
||||
```
|
||||
> state
|
||||
router
|
||||
Done
|
||||
```
|
||||
|
||||
## Step 5: Ping between devices
|
||||
|
||||
Demonstrate successful data path communication by sending/receiving ICMPv6 Echo
|
||||
request/response messages.
|
||||
|
||||
List all IPv6 addresses of Leader:
|
||||
|
||||
```
|
||||
> ipaddr
|
||||
fdde:ad00:beef:0:0:ff:fe00:fc00
|
||||
fdde:ad00:beef:0:0:ff:fe00:800
|
||||
fdde:ad00:beef:0:5b:3bcd:deff:7786
|
||||
fe80:0:0:0:6447:6e10:cf7:ee29
|
||||
Done
|
||||
```
|
||||
|
||||
Send an ICMPv6 ping from Router to Leader's Mesh-Local EID IPv6 address:
|
||||
|
||||
```
|
||||
> ping fdde:ad00:beef:0:5b:3bcd:deff:7786
|
||||
16 bytes from fdde:ad00:beef:0:5b:3bcd:deff:7786: icmp_seq=1 hlim=64 time=24ms
|
||||
```
|
||||
|
||||
## Step 6: Reset a device and validate reattachment
|
||||
|
||||
Demonstrate non-volatile functionality by resetting the device and validating
|
||||
its reattachment to the same network without user intervention.
|
||||
|
||||
Start a Thread network:
|
||||
|
||||
```
|
||||
> dataset init new
|
||||
Done
|
||||
> dataset
|
||||
Active Timestamp: 1
|
||||
Channel: 13
|
||||
Channel Mask: 07fff800
|
||||
Ext PAN ID: d63e8e3e495ebbc3
|
||||
Mesh Local Prefix: fd3d:b50b:f96d:722d/64
|
||||
Master Key: dfd34f0f05cad978ec4e32b0413038ff
|
||||
Network Name: OpenThread-8f28
|
||||
PAN ID: 0x8f28
|
||||
PSKc: c23a76e98f1a6483639b1ac1271e2e27
|
||||
Security Policy: 0, onrcb
|
||||
Done
|
||||
> dataset commit active
|
||||
Done
|
||||
> ifconfig up
|
||||
Done
|
||||
> thread start
|
||||
Done
|
||||
```
|
||||
|
||||
Wait a couple of seconds and verify that the active dataset has been stored in
|
||||
non-volatile storage:
|
||||
|
||||
```
|
||||
> dataset active
|
||||
Active Timestamp: 1
|
||||
Channel: 13
|
||||
Channel Mask: 07fff800
|
||||
Ext PAN ID: d63e8e3e495ebbc3
|
||||
Mesh Local Prefix: fd3d:b50b:f96d:722d/64
|
||||
Master Key: dfd34f0f05cad978ec4e32b0413038ff
|
||||
Network Name: OpenThread-8f28
|
||||
PAN ID: 0x8f28
|
||||
PSKc: c23a76e98f1a6483639b1ac1271e2e27
|
||||
Security Policy: 0, onrcb
|
||||
Done
|
||||
```
|
||||
|
||||
Reset the device:
|
||||
|
||||
```
|
||||
> reset
|
||||
> ifconfig up
|
||||
Done
|
||||
> thread start
|
||||
Done
|
||||
```
|
||||
|
||||
Wait a couple of seconds and verify that the device has successfully reattached
|
||||
to the network:
|
||||
|
||||
```
|
||||
> panid
|
||||
0x8f28
|
||||
Done
|
||||
> state
|
||||
router
|
||||
Done
|
||||
```
|
||||
|
||||
## Step 7: Verify random number generation
|
||||
|
||||
Demonstrate random number generation by executing the `factoryreset` command and
|
||||
verifying a new random extended address.
|
||||
|
||||
```
|
||||
> extaddr
|
||||
a660421703f3fdc3
|
||||
Done
|
||||
> factoryreset
|
||||
```
|
||||
|
||||
Wait a couple of seconds...
|
||||
|
||||
```
|
||||
> extaddr
|
||||
9a8ed90715a5f7b6
|
||||
Done
|
||||
```
|
||||
Reference in New Issue
Block a user