diff --git a/README.md b/README.md index 6abcce26b..8a06bb434 100644 --- a/README.md +++ b/README.md @@ -14,11 +14,11 @@ OpenThread is... **...an open-source implementation of the [Thread](http://threadgroup.org/technology/ourtechnology) networking protocol.** Nest has released OpenThread to make the technology used in Nest products more broadly available to developers to accelerate the development of products for the connected home. -**...OS and platform agnostic**, with a narrow platform abstraction layer and a small memory footprint, making it highly portable. +**...OS and platform agnostic**, with a narrow platform abstraction layer and a small memory footprint, making it highly portable. It supports both system-on-chip (SoC) and network co-processor (NCP) designs. -**...a Thread Certified Component**, implementing all features defined in the [Thread 1.1.1 specification](http://threadgroup.org/technology/ourtechnology#specifications). This specification defines an IPv6-based reliable, secure and low-power wireless device-to-device communication protocol for home applications. +**...a Thread Certified Component**, implementing all features defined in the [Thread 1.1.1 specification](http://threadgroup.org/technology/ourtechnology#specifications), including all Thread networking layers (IPv6, 6LoWPAN, IEEE 802.15.4 with MAC security, Mesh Link Establishment, Mesh Routing) and device roles, as well as [Border Router](https://github.com/openthread/borderrouter) support. -More information about Thread can be found on [threadgroup.org](http://threadgroup.org/). +More information about Thread can be found at [threadgroup.org](http://threadgroup.org/). [thread]: http://threadgroup.org/technology/ourtechnology [ot-repo]: https://github.com/openthread/openthread @@ -30,150 +30,32 @@ More information about Thread can be found on [threadgroup.org](http://threadgro [ot-codecov]: https://codecov.io/gh/openthread/openthread [ot-codecov-svg]: https://codecov.io/gh/openthread/openthread/branch/master/graph/badge.svg -# Get started with OpenThread - - -OpenThread Codelab - - -Want to try OpenThread? The quickest way to get started is to run through our [Simulation Codelab](https://codelabs.developers.google.com/codelabs/openthread-simulation/index.html), which covers all the basics, without the need for test hardware. Using VirtualBox and Vagrant on a Mac or Linux machine, you will learn: - -* How to set up the OpenThread build toolchain -* How to simulate a Thread network -* How to authenticate Thread nodes with Commissioning -* How to use `wpantund` to manage a simulated Thread network featuring an NCP - -### Next Steps - -The Codelab shows you how easy it is use to OpenThread to simulate a Thread network. Once complete: - -1. Learn more about the [OpenThread architecture and features](#openthread-features) -1. Get familiar with [platforms and devices that support OpenThread](#who-supports-openthread) -1. See what [testing tools](#what-tools-are-available-for-testing) are available -1. Learn [where to get help](#need-help) and [how to contribute](#want-to-contribute) to the ongoing development of OpenThread - -# OpenThread Features - -OpenThread implements all features defined in the [Thread 1.1.1 specification](http://threadgroup.org/technology/ourtechnology#specifications), including all Thread networking layers (IPv6, 6LoWPAN, IEEE 802.15.4 with MAC security, Mesh Link Establishment, Mesh Routing) and device roles, as well as [Border Router](https://github.com/openthread/borderrouter) support. - -OpenThread supports both system-on-chip (SoC) and network co-processor (NCP) designs. Other features and enhancements include: - -* Application support and services - * IPv6 configuration and raw data interface - * UDP sockets - * CoAP client and server - * DHCPv6 client and server - * DNSv6 client - * Command Line Interface (CLI) -* NCP support - * Spinel - general purpose NCP protocol - * `wpantund` - user-space NCP network interface driver/daemon - * Sniffer support via NCP Spinel nodes -* Border Router - * Web UI for configuration and management - * Thread Border Agent to support an External Commissioner - * NAT64 for connecting to IPv4 networks - * Thread interface driver using `wpantund` - -### What's coming? - -The development of OpenThread is ongoing to provide additional features not available in the standard. Check back regularly for new updates, or visit the [openthread-announce](https://groups.google.com/forum/#!forum/openthread-announce) Google Group. - # Who supports OpenThread? Led by Nest, the following companies are contributing to the ongoing development of OpenThread: -ARMAtmelDialogMicrosoftNestNordicNXPQorvoQualcommSynopsysTexas Instruments +ARMDialogMicrosoftNestNordicNXPQorvoQualcommSynopsysTexas Instruments -OpenThread has been ported to several devices and platforms by both the OpenThread team and the community. Build examples for all supported platforms are included in the OpenThread project. +# Getting started -### IEEE 802.15.4 Platform Support +All end-user documentation and guides are located at [openthread.io](https://openthread.io). If you're looking to do things like... -* [Dialog Semiconductor DA15000](https://github.com/openthread/openthread/wiki/Platforms#dialog-da15000) -* [Nordic Semiconductor nRF52840](https://github.com/openthread/openthread/wiki/Platforms#nordic-semiconductor-nrf52840) -* [NXP KW41Z](https://github.com/openthread/openthread/wiki/Platforms#nxp-kw41z) -* [Qorvo GP712](https://github.com/openthread/openthread/wiki/Platforms#qorvo-gp712) -* [Silicon Labs EFR32](https://github.com/openthread/openthread/wiki/Platforms#silicon-labs-efr32) -* [Synopsys ARC EMSK with Microchip MRF24J40](https://github.com/openthread/openthread/wiki/Platforms#synopsys-arc-em-with-microchip-mrf24j40) -* [Texas Instruments CC2538](https://github.com/openthread/openthread/wiki/Platforms#texas-instruments-cc2538) -* [Texas Instruments CC2650](https://github.com/openthread/openthread/wiki/Platforms#texas-instruments-cc2650) -* [Texas Instruments CC2652](https://github.com/openthread/openthread/wiki/Platforms#texas-instruments-cc2652) -* [POSIX Emulation](https://github.com/openthread/openthread/wiki/Platforms#posix-emulation) +* Learn more about OpenThread features and enhancements +* Use OpenThread in your products +* Learn how to build and configure a Thread network +* Port OpenThread to a new platform +* Build an application on top of OpenThread +* Certify a product using OpenThread -See the [Wiki Platform page](https://github.com/openthread/openthread/wiki/Platforms) for more detailed information on supported platforms. +...then [openthread.io](https://openthread.io) is the place for you. -### Desktop Support +If you're interested in contributing to OpenThread, read on. -Desktop platforms can also be used to control and interface with a Thread network using OpenThread: +# Contributing -* **Unix** — [`wpantund`](https://github.com/openthread/wpantund) provides an interface to an NCP -* **Windows 10** — [universal drivers](https://github.com/openthread/openthread/wiki/OpenThread-on%C2%A0Windows) to interface with devices running OpenThread +We would love for you to contribute to OpenThread and help make it even better than it is today! See our [Contributing Guidelines](https://github.com/openthread/openthread/blob/master/CONTRIBUTING.md) for more information. -### Porting - -If you are interested in porting OpenThread to a new platform, see the [Porting Guide](https://github.com/openthread/openthread/wiki/Porting-Guide) for hardware requirements and detailed porting instructions. - -### Border Router - -A Border Router connects a Thread network to networks at different layers, such as WiFi or Ethernet. [OpenThread Border Router](https://github.com/openthread/borderrouter) provides end-to-end IP via routing between Thread devices and other external IP networks, as well as external Thread Commissioning. - -# What tools are available for testing? - -### Certification Testing - -Certification testing is done with the [GRL Thread Test Harness software](http://graniteriverlabs.com/thread/), available for download to Thread member companies. - -Additional tools that extend the Test Harness are included in the OpenThread project: - -* [Thread Harness Automation](https://github.com/openthread/openthread/tree/master/tools/harness-automation) — automates the Thread Test Harness software -* [Thread Harness THCI for OpenThread](https://github.com/openthread/openthread/tree/master/tools/harness-thci) — allows the Thread Test Harness to control OpenThread-based reference devices directly - * CC2538 example included in the GRL Thread Test Hardness software - * Library version can be modified by developers for use on other platforms - -### Sniffer - -OpenThread also provides a [sniffer](https://github.com/openthread/openthread/blob/master/tools/spinel-cli/SNIFFER.md) on the NCP build. The sniffer is exposed by the Spinel protocol and features: - -* Monitor mode — capture packets during operation -* Promiscuous mode — dedicated sniffer -* Host-side support — `wpantund` -* pcap stream output - -# Need help? - -### Wiki - -Explore the [OpenThread Wiki](https://github.com/openthread/openthread/wiki) for more in-depth documentation on building, testing, automation and tools. - -### Interact - -There are numerous avenues for OpenThread support: - -* Bugs and feature requests — [submit to the Issue Tracker](https://github.com/openthread/openthread/issues) -* Stack Overflow — [post questions using the `openthread` tag](http://stackoverflow.com/questions/tagged/openthread) -* Google Groups — discussion and announcements - * [openthread-announce](https://groups.google.com/forum/#!forum/openthread-announce) — release notes and new updates on OpenThread - * [openthread-users](https://groups.google.com/forum/#!forum/openthread-users) — the best place for users to discuss OpenThread and interact with the OpenThread team - -### Directory Structure - -The OpenThread repository is structured as follows: - -Folder | Contents ---------------|---------------------------------------------------------------- -`doc` | Spinel docs and Doxygen build file -`etc` | Configuration files for other build systems (e.g. Visual Studio) -`examples` | Sample applications and platforms demonstrating OpenThread -`include` | Public API header files -`src` | Core implementation of the Thread standard and related add-ons -`tests` | Unit and Thread conformance tests -`third_party` | Third-party code used by OpenThread -`tools` | Helpful utilities related to the OpenThread project - - -# Want to contribute? - -We would love for you to contribute to OpenThread and help make it even better than it is today! See the [`CONTRIBUTING.md`](https://github.com/openthread/openthread/blob/master/CONTRIBUTING.md) file for more information. +Contributors are required to abide by our [Code of Conduct](https://github.com/openthread/openthread/blob/master/CODE_OF_CONDUCT.md) and [Coding Conventions and Style Guide](https://github.com/openthread/openthread/blob/master/STYLE_GUIDE.md). # Versioning @@ -184,3 +66,13 @@ OpenThread follows the [Semantic Versioning guidelines](http://semver.org/) for OpenThread is released under the [BSD 3-Clause license](https://github.com/openthread/openthread/blob/master/LICENSE). See the [`LICENSE`](https://github.com/openthread/openthread/blob/master/LICENSE) file for more information. Please only use the OpenThread name and marks when accurately referencing this software distribution. Do not use the marks in a way that suggests you are endorsed by or otherwise affiliated with Nest, Google, or The Thread Group. + +# Need help? + +There are numerous avenues for OpenThread support: + +* Bugs and feature requests — [submit to the Issue Tracker](https://github.com/openthread/openthread/issues) +* Stack Overflow — [post questions using the `openthread` tag](http://stackoverflow.com/questions/tagged/openthread) +* Google Groups — [discussion and announcements at openthread-users](https://groups.google.com/forum/#!forum/openthread-users) + +The openthread-users Google Group is the recommended place for users to discuss OpenThread and interact directly with the OpenThread team. diff --git a/examples/drivers/windows/README.md b/examples/drivers/windows/README.md index 9d1e9c911..4e18c92e0 100644 --- a/examples/drivers/windows/README.md +++ b/examples/drivers/windows/README.md @@ -1,54 +1,163 @@ # OpenThread on Windows # -These components are the building blocks to get OpenThread integrated into the Windows -networking stack and provide an interface for applications to control it. +OpenThread includes Windows 10 drivers necessary for interfacing with UART NCP devices. The design allows for support of both simple radio devices and devices running the complete OpenThread stack. ## Architecture ## -[ndis]: https://msdn.microsoft.com/en-us/windows/hardware/drivers/network/ndis-drivers -[lwf]: https://msdn.microsoft.com/en-us/windows/hardware/drivers/network/ndis-filter-drivers -[miniport]: https://msdn.microsoft.com/en-us/windows/hardware/drivers/network/ndis-miniport-drivers2 -[ioctl]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363219(v=vs.85).aspx -[oid]: https://msdn.microsoft.com/en-us/library/windows/hardware/ff566707(v=vs.85).aspx -[nbl]: https://msdn.microsoft.com/en-us/windows/hardware/drivers/network/net-buffer-architecture +Details on the architecture can be found [here](https://openthread.io/platforms/windows10). -![Windows Architecture](../../../doc/images/windows_design.png) +## Building OpenThread using Windows -This design allows for support of both simple radio devices and devices running the complete -OpenThread stack. +To build locally using the Windows platform, use Visual Studio 2015. To build for the POSIX and TI CC2538 platforms, use Bash on Ubuntu on Windows. -### otApi.dll ### +All the following steps assume you have already cloned and checked out a branch. -This is the dynamic libray for applications to control the OpenThread stack from user mode. It -exposes all the control path APIs from `openthread.h`. It interfaces with the driver by the use -of [IOCTL][ioctl]s. The IOCTLs allow otApi.dll to serialize and send commands, and poll for notifications, -which can then be returned back to the client. +### Visual Studio 2015 -### otLwf.sys ### +To build OpenThread on Windows you need to install the following: -This is where most of the real logic lives. `otLwf.sys` is an [NDIS][ndis] Light Weight Filter ([LWF][lwf]) driver. -It plugs into the networking stack, binding to a protocol driver (TCPIP) at the top, and an NDIS [Miniport][miniport] -at the bottom. It's job is to take IPv6 packets from TCPIP and pass the necessary data down to the Miniport -in order to send the packets out over the network. +* Any Visual Studio 2015 edition. The [Community](https://www.microsoft.com/en-us/download/details.aspx?id=48146) edition is free. Generally most of the optional features will be required. +* The [Windows 10 Driver Kit](https://go.microsoft.com/fwlink/p/?LinkId=526733). -`otLwf.sys` supports operating in two modes: Full Stack and Tunnel. Full Stack mode is where OpenThread is -running on the host (in Windows) and a simple radio device is connected externally. Tunnel mode is where -OpenThread is running on the external device and Windows is merely a pass through for commands and packets. +Once all these are installed, open the Solution file `etc/visual-studio/openthread.sln`. Select the Configuration and Platform (i.e. Release/x64) and then Build All (F6). -In both cases, `otLwf.sys` uses the Spinel command interface for interacting with the connected device. When operating -in Full Stack mode, `otLwf.sys` uses only the low level PHY/MAC commands. In Tunnel mode, it uses the higher layer -Spinel commands and lets the device manage the actual Thread stack. +### Bash on Ubuntu on Windows -### ottmp.sys ### +[Bash on Ubuntu on Windows](https://msdn.microsoft.com/en-us/commandline/wsl/about) is a new feature to Windows 10. To set it up, follow the steps [here](https://msdn.microsoft.com/commandline/wsl/install_guide). Other FAQs can be found [here](https://msdn.microsoft.com/en-us/commandline/wsl/faq). -This is the component responsible passing the Spinel commands from `otLwf.sys` down to the device. It is responsible -for abstracting the actual mechanism (USB, Serial, SPI) used for communicating with the device. It handles the device -arrival/removal and the encoding/decoding of data when communicating with it. The current implementation only handles -Serial devices. +Once installed, open the "Bash on Ubuntu on Windows" app. Do the following to install everything necessary to build OpenThread. -### Device ### +Make sure line ending are UNIX style: -Windows supports OpenThread devices that implement the Spinel protocol. It supports devices that support either the raw -link-layer PHY/MAC commands and devices that support the Thread commands (and devices that support both). By default, -Windows will operate in Full Stack mode, only sending raw link-layer commands. +``` +git config core.autocrlf false +git rm --cached -r . && git reset --hard +``` +Install the compilers: + +``` +apt install gcc +apt install g++ +``` + +Install Python (with pexpect): + +``` +apt install python +apt install python-pip +pip install pexpect +``` + +To build the TI CC2538 platform, you need to install the correct toolchain: + +``` +add-apt-repository ppa:team-gcc-arm-embedded/ppa +apt-get update +apt-get install gcc-arm-embedded +``` + +Set up the build environment: + +``` +./bootstrap +``` + +### Platforms + +Before building, manually configure features as desired. For example: + +``` +./configure --enable-cli --enable-diag --enable-commissioner --enable-joiner --with-examples=posix +make +``` + +Or clean and build with desired features enabled: + +``` +make -f examples/Makefile- clean +COMMISSIONER=1 JOINER=1 make -f examples/Makefile- +``` + +For detailed instructions on building and creating binaries for Windows-supported platforms, see each platform's respective README: + +* [POSIX](https://github.com/openthread/openthread/tree/master/examples/platforms/posix) +* [TI CC2538](https://github.com/openthread/openthread/tree/master/examples/platforms/cc2538) +* [Nordic nRF52840](https://github.com/openthread/openthread/tree/master/examples/platforms/nrf52840) + +## Installing OpenThread on Windows + +Microsoft has made available a test VHD specifically modified for virtually testing OpenThread. To get access, please email `nibanks` via his `@microsoft.com` email address. + +Once the Windows VHD is loaded and you have gone through OOBE, see `C:\OpenThread\readme.txt` for additional instructions on how to set everything up. + +> **Note:** Since none of the binaries mentioned below are production signed; you need to enable test signing on the machine: `bcdedit /set testsigning on`. All these binaries require Windows 10 at a minimum. + +Since most of these drivers are still under development, it is recommended to also have a kernel debugger configured for the test machine. + +### otlwf.sys & otapi.dll + +The filter driver `otlwf.sys` exposes the IOCTL interface that `otapi.dll` uses and houses the bulk of the actual Thread logic. `otapi.dll` exposes the C interface for user mode applications to use to control the Thread interfaces. + +1. Download the latest binaries ([x86](https://ci.appveyor.com/api/projects/jwhui/openthread/artifacts/release.zip?job=Platform%3A+x86), [x64](https://ci.appveyor.com/api/projects/jwhui/openthread/artifacts/release.zip?job=Platform%3A+x64), [arm](https://ci.appveyor.com/api/projects/jwhui/openthread/artifacts/release.zip?job=Platform%3A+arm)) +1. Extract the files to a temporary location +1. Open an admin command prompt in the temporary location +1. Run the `install_otlwf.cmd` file +1. On **non-IoT platforms**, install the [Visual C++ Redistributable for Visual Studio 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48145) +1. **Note:** A reboot is required, but can be done after all installation is complete. + +### ottmp.sys (Miniport for Serial Devices) + +The miniport driver `ottmp.sys` binds to serial devices on the machine and exposes them to `otlwf.sys`. It is only needed if you are connecting to an actual device (such as the TI CC2538 or Nordic Semiconductor nRF52840 device). + +1. Open an admin command prompt (same location as above). +1. Run the install_ottmp.cmd file. +1. **Note:** A reboot is required, but can be done after all installation is complete. +1. Once the test machine boots and the serial device is connected, manually restart the miniport so that it can find the serial device. **This will have to be done for every reboot**: +``` +devcon.exe restart *ottmp* +``` + +### Command Line Tool Usage + +The command line tool `otCli.exe` exposes many of the APIs in `otApi.dll` via the command line. It is included with the same release binaries downloaded above. See the [CLI example README](https://github.com/openthread/openthread/blob/master/examples/apps/cli/README.md) for more details. + +The main differences between `otCli.exe` on Windows and the `ot-cli` on Linux, are the following: + +* On Linux, the CLI runs the actual OpenThread stack in-proc. On Windows, it just provides an interface to control the OpenThread stack running either in the installed driver or on the physical device. +* On Windows, the CLI supports multiple interfaces simultaneously via the `instance` and `instancelist` commands. + +The `instance` command allows for getting/setting the current instance that the rest of the commands act on. + +``` +> instance 0 +Done +> instance +[0] {01234567-89AB-CDEF-0123-4567890ABCDE} (Compartment 1) +``` + +The `instancelist` command queries for all available instances/interfaces on the machine. + +``` +> instancelist +1 instances found: +[0] {01234567-89AB-CDEF-0123-4567890ABCDE} (Compartment 1) +``` + +### Sample Universal App + +The latest build of the sample universal app can be downloaded from ([x86](https://ci.appveyor.com/api/projects/jwhui/openthread/artifacts/build/bin/app.zip?job=Platform%3A+x86), [x64](https://ci.appveyor.com/api/projects/jwhui/openthread/artifacts/build/bin/app.zip?job=Platform%3A+x64), [arm](https://ci.appveyor.com/api/projects/jwhui/openthread/artifacts/build/bin/app.zip?job=Platform%3A+arm)). + +### Running Python Certification Tests + +The Python certification tests approximate the testing done for real certification. On Windows they are run using virtual OpenThread devices. To set up the environment: + +1. Install Python 3.6 to `C:\Python36` for all users. Make sure to add the install path to `PATH`. +1. Install the Python crypto libraries: `python.exe C:\Python36\Scripts\pip.exe install pycryptodome==3.4.3` +1. Copy Python cert scripts to the machine (to a 'scripts' folder) + +To run all the tests: + +``` +otTestRunner.exe scripts Cert_* parallel:4 retry:2 +``` \ No newline at end of file diff --git a/include/openthread/border_router.h b/include/openthread/border_router.h index f5eefd7ab..5a8150d6e 100644 --- a/include/openthread/border_router.h +++ b/include/openthread/border_router.h @@ -98,7 +98,7 @@ OTAPI otError OTCALL otBorderRouterRemoveOnMeshPrefix(otInstance *aInstance, con * @param[in] aInstance A pointer to an OpenThread instance. * @param[inout] aIterator A pointer to the Network Data iterator context. To get the first on-mesh entry it should be set to OT_NETWORK_DATA_ITERATOR_INIT. - * @param[out] aConfig A pointer to where the On Mesh Prefix information will be placed. + * @param[out] aConfig A pointer to the On Mesh Prefix information. * * @retval OT_ERROR_NONE Successfully found the next On Mesh prefix. * @retval OT_ERROR_NOT_FOUND No subsequent On Mesh prefix exists in the Thread Network Data. @@ -142,7 +142,7 @@ OTAPI otError OTCALL otBorderRouterRemoveRoute(otInstance *aInstance, const otIp * @param[in] aInstance A pointer to an OpenThread instance. * @param[inout] aIterator A pointer to the Network Data iterator context. To get the first external route entry it should be set to OT_NETWORK_DATA_ITERATOR_INIT. - * @param[out] aConfig A pointer to where the External Route information will be placed. + * @param[out] aConfig A pointer to the External Route information. * * @retval OT_ERROR_NONE Successfully found the next External Route. * @retval OT_ERROR_NOT_FOUND No subsequent external route entry exists in the Thread Network Data. diff --git a/include/openthread/child_supervision.h b/include/openthread/child_supervision.h index 6820b6c54..1c54db754 100644 --- a/include/openthread/child_supervision.h +++ b/include/openthread/child_supervision.h @@ -60,7 +60,7 @@ extern "C" { * * Child supervision feature provides a mechanism for parent to ensure that a message is sent to each sleepy child * within the supervision interval. If there is no transmission to the child within the supervision interval, - * OpenThread will enqueue and send a supervision message (a data message with empty payload) to the child. + * OpenThread enqueues and sends a supervision message (a data message with empty payload) to the child. * * @param[in] aInstance A pointer to an OpenThread instance. * diff --git a/include/openthread/commissioner.h b/include/openthread/commissioner.h index f824e2e78..facbae7d9 100644 --- a/include/openthread/commissioner.h +++ b/include/openthread/commissioner.h @@ -275,7 +275,7 @@ OTAPI otCommissionerState OTCALL otCommissionerGetState(otInstance *aInstance); * @param[in] aPassPhrase The commissioning passphrase. * @param[in] aNetworkName The network name for PSKc computation. * @param[in] aExtPanId The extended pan id for PSKc computation. - * @param[out] aPSKc A pointer to where the generated PSKc will be placed. + * @param[out] aPSKc A pointer to the generated PSKc. * * @retval OT_ERROR_NONE Successfully generate PSKc. * @retval OT_ERROR_INVALID_ARGS If any of the input arguments is invalid. diff --git a/include/openthread/icmp6.h b/include/openthread/icmp6.h index f927a1be1..5ba9826c8 100644 --- a/include/openthread/icmp6.h +++ b/include/openthread/icmp6.h @@ -146,7 +146,7 @@ void otIcmp6SetEchoEnabled(otInstance *aInstance, bool aEnabled); /** * This function registers a handler to provide received ICMPv6 messages. * - * @note A handler structure @p aHandler has to be stored in persistant (static) memory. + * @note A handler structure @p aHandler has to be stored in persistent (static) memory. * OpenThread does not make a copy of handler structure. * * @param[in] aInstance A pointer to an OpenThread instance. diff --git a/include/openthread/ip6.h b/include/openthread/ip6.h index 9dab4f0bd..da1d64d73 100644 --- a/include/openthread/ip6.h +++ b/include/openthread/ip6.h @@ -80,7 +80,7 @@ OTAPI bool OTCALL otIp6IsEnabled(otInstance *aInstance); /** * Add a Network Interface Address to the Thread interface. * - * The passed in instance @p aAddress will be copied by the Thread interface. The Thread interface only + * The passed-in instance @p aAddress is copied by the Thread interface. The Thread interface only * supports a fixed number of externally added unicast addresses. See OPENTHREAD_CONFIG_MAX_EXT_IP_ADDRS. * * @param[in] aInstance A pointer to an OpenThread instance. diff --git a/include/openthread/link.h b/include/openthread/link.h index 753e3de83..aa6e05914 100644 --- a/include/openthread/link.h +++ b/include/openthread/link.h @@ -164,8 +164,8 @@ OTAPI uint8_t OTCALL otLinkGetChannel(otInstance *aInstance); /** * Set the IEEE 802.15.4 channel * - * This function will only succeed when Thread protocols are disabled. A successful - * call to this function will also invalidate the Active and Pending Operational Datasets in + * This function succeeds only when Thread protocols are disabled. A successful + * call to this function invalidates the Active and Pending Operational Datasets in * non-volatile memory. * * @param[in] aInstance A pointer to an OpenThread instance. @@ -191,7 +191,7 @@ OTAPI const otExtAddress *OTCALL otLinkGetExtendedAddress(otInstance *aInstance) /** * This function sets the IEEE 802.15.4 Extended Address. * - * This function will only succeed when Thread protocols are disabled. + * This function succeedsm only when Thread protocols are disabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aExtAddress A pointer to the IEEE 802.15.4 Extended Address. @@ -257,8 +257,8 @@ OTAPI otPanId OTCALL otLinkGetPanId(otInstance *aInstance); /** * Set the IEEE 802.15.4 PAN ID. * - * This function will only succeed when Thread protocols are disabled. A successful - * call to this function will also invalidate the Active and Pending Operational Datasets in + * This function succeeds only when Thread protocols are disabled. A successful + * call to this function also invalidates the Active and Pending Operational Datasets in * non-volatile memory. * * @param[in] aInstance A pointer to an OpenThread instance. diff --git a/include/openthread/message.h b/include/openthread/message.h index 31c26dc83..987f6ee46 100644 --- a/include/openthread/message.h +++ b/include/openthread/message.h @@ -155,8 +155,8 @@ bool otMessageIsLinkSecurityEnabled(otMessage *aMessage); * Default setting for a new message is `false`. * * @param[in] aMessage A pointer to a message buffer. - * @param[in] aEnabled If `true` message will be forced to use direct transmission. If `false` message will - * follow the normal procedure. + * @param[in] aEnabled If `true`, the message is forced to use direct transmission. If `false`, the + * message follows the normal procedure. * */ void otMessageSetDirectTransmission(otMessage *aMessage, bool aEnabled); diff --git a/include/openthread/platform/radio.h b/include/openthread/platform/radio.h index af157925b..89201d25d 100644 --- a/include/openthread/platform/radio.h +++ b/include/openthread/platform/radio.h @@ -158,7 +158,7 @@ typedef enum otRadioState * Get the factory-assigned IEEE EUI-64 for this interface. * * @param[in] aInstance The OpenThread instance structure. - * @param[out] aIeeeEui64 A pointer to where the factory-assigned IEEE EUI-64 will be placed. + * @param[out] aIeeeEui64 A pointer to the factory-assigned IEEE EUI-64. * */ void otPlatRadioGetIeeeEui64(otInstance *aInstance, uint8_t *aIeeeEui64); @@ -387,7 +387,7 @@ otRadioFrame *otPlatRadioGetTransmitBuffer(otInstance *aInstance); * 2. Transmits the psdu on the given channel and at the given transmit power. * * @param[in] aInstance The OpenThread instance structure. - * @param[in] aFrame A pointer to the frame that will be transmitted. + * @param[in] aFrame A pointer to the transmitted frame. * * @retval OT_ERROR_NONE Successfully transitioned to Transmit. * @retval OT_ERROR_INVALID_STATE The radio was not in the Receive state. diff --git a/include/openthread/platform/random.h b/include/openthread/platform/random.h index 06bf89af5..6c40e325e 100644 --- a/include/openthread/platform/random.h +++ b/include/openthread/platform/random.h @@ -56,7 +56,7 @@ extern "C" { /** * Get a 32-bit random value. * - * This function may be implemented using a psuedo-random number generator. + * This function may be implemented using a pseudo-random number generator. * * @returns A 32-bit random value. * diff --git a/include/openthread/thread.h b/include/openthread/thread.h index 4769c7235..8adfade2f 100644 --- a/include/openthread/thread.h +++ b/include/openthread/thread.h @@ -160,8 +160,8 @@ OTAPI const uint8_t *OTCALL otThreadGetExtendedPanId(otInstance *aInstance); /** * Set the IEEE 802.15.4 Extended PAN ID. * - * This function may only be called while Thread protocols are disabled. A successful - * call to this function will also invalidate the Active and Pending Operational Datasets in + * This function can only be called while Thread protocols are disabled. A successful + * call to this function invalidates the Active and Pending Operational Datasets in * non-volatile memory. * * @param[in] aInstance A pointer to an OpenThread instance. @@ -178,7 +178,7 @@ OTAPI otError OTCALL otThreadSetExtendedPanId(otInstance *aInstance, const uint8 * This function returns a pointer to the Leader's RLOC. * * @param[in] aInstance A pointer to an OpenThread instance. - * @param[out] aLeaderRloc A pointer to where the Leader's RLOC will be written. + * @param[out] aLeaderRloc A pointer to the Leader's RLOC. * * @retval OT_ERROR_NONE The Leader's RLOC was successfully written to @p aLeaderRloc. * @retval OT_ERROR_INVALID_ARGS @p aLeaderRloc was NULL. @@ -224,8 +224,8 @@ OTAPI const otMasterKey *OTCALL otThreadGetMasterKey(otInstance *aInstance); /** * Set the thrMasterKey. * - * This function will only succeed when Thread protocols are disabled. A successful - * call to this function will also invalidate the Active and Pending Operational Datasets in + * This function succeeds only when Thread protocols are disabled. A successful + * call to this function invalidates the Active and Pending Operational Datasets in * non-volatile memory. * * @param[in] aInstance A pointer to an OpenThread instance. @@ -262,8 +262,8 @@ OTAPI const uint8_t *OTCALL otThreadGetMeshLocalPrefix(otInstance *aInstance); /** * This function sets the Mesh Local Prefix. * - * This function will only succeed when Thread protocols are disabled. A successful - * call to this function will also invalidate the Active and Pending Operational Datasets in + * This function succeeds only when Thread protocols are disabled. A successful + * call to this function invalidates the Active and Pending Operational Datasets in * non-volatile memory. * * @param[in] aInstance A pointer to an OpenThread instance. @@ -300,8 +300,8 @@ OTAPI const char *OTCALL otThreadGetNetworkName(otInstance *aInstance); /** * Set the Thread Network Name. * - * This function will only succeed when Thread protocols are disabled. A successful - * call to this function will also invalidate the Active and Pending Operational Datasets in + * This function succeeds only when Thread protocols are disabled. A successful + * call to this function invalidates the Active and Pending Operational Datasets in * non-volatile memory. * * @param[in] aInstance A pointer to an OpenThread instance. @@ -383,7 +383,7 @@ OTAPI otError OTCALL otThreadBecomeChild(otInstance *aInstance); * @param[in] aInstance A pointer to an OpenThread instance. * @param[inout] aIterator A pointer to the iterator context. To get the first neighbor entry it should be set to OT_NEIGHBOR_INFO_ITERATOR_INIT. - * @param[out] aInfo A pointer to where the neighbor information will be placed. + * @param[out] aInfo A pointer to the neighbor information. * * @retval OT_ERROR_NONE Successfully found the next neighbor entry in table. * @retval OT_ERROR_NOT_FOUND No subsequent neighbor entry exists in the table. diff --git a/include/openthread/types.h b/include/openthread/types.h index 0984ef5d4..9931330e0 100644 --- a/include/openthread/types.h +++ b/include/openthread/types.h @@ -650,7 +650,7 @@ typedef struct otLinkModeConfig bool mRxOnWhenIdle : 1; /** - * 1, if the sender will use IEEE 802.15.4 to secure all data requests. 0, otherwise. + * 1, if the sender uses IEEE 802.15.4 to secure all data requests. 0, otherwise. */ bool mSecureDataRequests : 1; @@ -771,7 +771,7 @@ typedef struct otExternalRouteConfig /** * The Rloc associated with the external route entry. * - * This value is ignored when adding an external route. For any added route the device's Rloc will be used. + * This value is ignored when adding an external route. For any added route, the device's Rloc is used. */ uint16_t mRloc16; diff --git a/src/ncp/Makefile.am b/src/ncp/Makefile.am index 9b5697613..c31ff4eb7 100644 --- a/src/ncp/Makefile.am +++ b/src/ncp/Makefile.am @@ -29,7 +29,6 @@ include $(abs_top_nlbuild_autotools_dir)/automake/pre.am EXTRA_DIST = \ - PROTOCOL.md \ $(NULL) # Pull in the sources that comprise the OpenThread NCP library. diff --git a/src/ncp/PROTOCOL.md b/src/ncp/PROTOCOL.md deleted file mode 100644 index f5aff6848..000000000 --- a/src/ncp/PROTOCOL.md +++ /dev/null @@ -1,7 +0,0 @@ -Spinel NCP Protocol Documentation -================================= - -This document has moved into the top level `doc` folder and renamed -[`draft-spinel-protocol.txt`](../../doc/draft-spinel-protocol.txt) -and [`draft-spinel-protocol.html`](../../doc/draft-spinel-protocol.html). - diff --git a/tools/harness-automation/README.rst b/tools/harness-automation/README.rst index 25fe76d64..857d341c9 100644 --- a/tools/harness-automation/README.rst +++ b/tools/harness-automation/README.rst @@ -5,10 +5,10 @@ Harness Automation Tool This is a tool to automate testing openthread with GRL Thread-Test-Harness1.1-Alpha v1.0-Release_40.0. ----------- -Quick Start +Get Started ----------- -Follow the `Quick Start `_ +To get started, follow the `Automation Setup Guide `. ------ Syntax @@ -22,49 +22,6 @@ Syntax [--auto-reboot] [--manual-reset] [--list-devices] [NAME [NAME ...]] -------- -Options -------- - If ``-l`` is given, ``NAME`` is the serial port device name. Otherwise ``NAME`` is test case name. This enables running single or multiple test cases directly. -Other options:: - - -h, --help - Show help message and exit. - - --blacklist BLACKLIST_FILE, -b BLACKLIST_FILE - skip test cases listed in BLACKLIST_FILE. - - --pattern PATTERN, -p PATTERN - File name pattern, Default to all python files. - - --delete-blacklist, -d - Clear golden device blacklist on startup. By default, golden devices failed to be connected are kept in a blacklist automatically. Add this option to clear blacklist on startup. - - --name-greps NAME_GREPS, -g NAME_GREPS - Filter case by its name using filename matching syntax. Multiple this options are OR-ed to allow more tests. - - --skip SKIP, -k SKIP - Type of test case status to skip. ``e`` for error, ``f`` for fail, ``p`` for pass. If test case names are given by ``NAME``, this option will not work. - - --dry-run, -n - Just show what test case will be run. - - --result-file RESULT_FILE, -o RESULT_FILE - File to store and read current status. - - --list-file LIST_FILE, -i LIST_FILE - File to list cases names to test. - - --continue-from CONTINUE_FROM, -c CONTINUE_FROM - First case to test. - - --auto-reboot, -a - Restart system when harness cannot recover. This is a walk around to some issues, such as golden devices may not work after long time running and have to restart system. - - --manual-reset, -m - Reset devices manually, in case no PDU available so that reset golden devices have to be done manually. - - --list-devices, -l - List devices, including their version information. +Use ``./start.sh --help`` for a full list of options. \ No newline at end of file