tag	85d5e61b0138b362d02e244e122c8f5aaddafe09
tagger	Robert Quattlebaum <rquattlebaum@nestlabs.com>	Fri Mar 31 20:35:16 2017
object	0097803c69ff07b1b5c9eea102b858527c3da23d

New in 0.07.01
==============

* wpantund: Support for raw packet capture (Packet sniffing)
* wpantund: StatCollector: Add scan result info to the logs
* wpantund: Show load average when main loop is thrashing.
* wpantund: Refactor how the address list is handled.
* wpantund: NCPInstanceBase: Reset data pump NLPTs when entering a detached state
* wpantund: NCPInstanceBase: Make sure we clear the global address table upon reset
* wpantund: NCPInstanceBase: Improve information logged when kernel refuses packets.
* wpantund: NCPInstanceBase: Fix for failure to restart NCP after firmware upgrade.
* wpantund: NCPInstanceBase: Fix for disappearing addresses after NCP crash
* wpantund: NCPInstanceBase: Don't let port 0 be used to start commissioning.
* wpantund: NCPInstanceBase: Don't allow host sleep while NCP is being initialized
* wpantund: NCPInstanceBase: Detect and report invalid state transitions
* wpantund: NCPInstanceBase: Add support for default commissioning port.
* wpantund: NCPInstanceBase: Add `is_initializing_ncp()` and `set_initializing_ncp()`
* wpantund: NCPInstanceBase-NetInterface: Add mesh-local address (if non-zero) in `set_online()`
* wpantund: Measure prefix length in bits, not bytes
* wpantund: Fix xpanid set/get methods on big endian systems
* wpantund: Energy scan support
* wpantund: Adding NetworkRetain class and `wpanretain.sh` script
* wpantund: Add return status to set_ncp_version_string()
* wpantund: Add diagnostics(mfg) interface
* wpanctl: Print out an appropriate error when the interface doesn't exist
* wpanctl: Print node-type in `join`/`form` commands
* wpanctl: Fix for infinite recursion issue with getprop
* wpanctl: Do not use stdin or stdout as an l-value
* wpanctl: Change how setprop processes option arguments
* wpan-connman-plugin: Remove scanned networks upon a successful connect
* wpan-connman-plugin: Ensure that network info is retained in case of untimely Connman restarts
* wpan-connman-plugin: Change the parsing of the MeshLocalPrefix value
* utils: Added secure random number functions
* socket-utils: Use constant macros for setting baud rate.
* socket-utils: Rename `*_serial_socket()` to `*_super_socket()`.
* socket-utils: Ensure child processes are terminated upon socket close
* socket-utils: Allow the explicit specification of a TCP socket.
* socket-utils: Add serial options `crts_iflow` and `ccts_oflow`.
* run-in-docker: Change base image from `gcc` to `ubuntu:trusty`.
* openthread: Support for OpenThread as of commit 27ddb2d2
* openthread: Include building spi-hdlc-adapter for convenience
* ncp-spinel: Updates for pcap support
* ncp-spinel: Topology support
* ncp-spinel: SpinelNCPTaskLeave: After `leave` clear `mNetworkKey` and `mNetworkKeyIndex`
* ncp-spinel: SpinelNCPInstance: Switch NCP log messages to log as `warning`
* ncp-spinel: SpinelNCPInstance: Add support for newly added NCP counters.
* ncp-spinel: SpinelNCPControlInterface: Fix for `permit_join 0` to make wpan non-joinable
* ncp-spinel: Remove obsolete `start_new_task()` design pattern
* ncp-spinel: Refine and clarify how MAC addresses are handled.
* ncp-spinel: Recovery mechanism for back-to-back NOMEM status from NCP
* ncp-spinel: Quick fix for bad buffer-overflow check in 910769e
* ncp-spinel: Parsing improvement for PROP_THREAD_ASSISTING_PORTS.
* ncp-spinel: Minor changes to improve Spinel support.
* ncp-spinel: Minor bug fixes and cleanups.
* ncp-spinel: Log data from PROP_STREAM_DEBUG to SysLog
* ncp-spinel: Join: Allow `ALREADY` error when setting `PROP_NET_IF_UP`
* ncp-spinel: Issue a "reset" at the end of "leave".
* ncp-spinel: Include Spinel TID value in info prints.
* ncp-spinel: Improved logging. Handle garbage on the line in a better way.
* ncp-spinel: Implement support for jam detection
* ncp-spinel: If HDLC frames with bad CRCs are ASCII, the log them.
* ncp-spinel: Have "Form" generate PANID, XPANID, and Mesh-local Prefix
* ncp-spinel: Handle adding and removing of unicast addresses.
* ncp-spinel: Fix for setting non-config properties in configuration file
* ncp-spinel: Fix for incorrectly calculating time for next event
* ncp-spinel: Fix for `remove_external_route()`.
* ncp-spinel: Fix config_gateway, add/remove external route
* ncp-spinel: Fix a buffer-overflow bug in the inbound data pump.
* ncp-spinel: Fetch counters as 32-bit integers, not 8-bit integers.
* ncp-spinel: Fault state should be recoverable by reset
* ncp-spinel: Erase saved network info before `form`, `join` and after `leave`
* ncp-spinel: Ensure the event-handler gets the original spinel data message
* ncp-spinel: Ensure stable flag is true for on-mesh-prefix added from `address_was_added()`
* ncp-spinel: Don't remove addresses from NCP while interface is down.
* ncp-spinel: Don't clear addresses when we get a new IPv6 address table.
* ncp-spinel: Consolidate and refine behavior of SendCommand task
* ncp-spinel: Check for time out error when adding address/on-mesh-prefix
* ncp-spinel: Change to `ISOLATED` state upon receiving `NET_ROLE_DETACHED` event from NCP
* ncp-spinel: Allow the network key to be specified when forming.
* ncp-spinel: Allow the channel to be set for join.
* ncp-spinel: Allow spinel driver to enter assisting/permit-join mode.
* ncp-spinel: Allow leave command to work even while NCP is initializing.
* ncp-spinel: Adding support to set/get legacy ULA prefix and retain it in the settings map
* ncp-spinel: Adding support for getting child table
* ncp-spinel: Add the ability to specify a specific channel when forming.
* ncp-spinel: Add supported channels set and use it during `form` if none is given
* ncp-spinel: Add support to save and restore certain radio properties during initialization
* ncp-spinel: Add support for unicast/broadcast counters (#108)
* ncp-spinel: Add support for promiscuous packet capture
* ncp-spinel: Add support for new property "JamDetection:Debug:HistoryBitmap"
* ncp-spinel: Add support for joining as an end-device
* ncp-spinel: Add support for in-band assisted joining
* ncp-spinel: Add support for handling the legacy commands
* ncp-spinel: Add support for getting neighbor table
* ncp-spinel: Add support for getting msg buffer counters from NCP
* ncp-spinel: Add support for Spinel counters.
* ncp-spinel: Add support for Energy Scan operation
* ncp-spinel: Add new properties to get leader network data
* ncp-spinel: Add new Thread wpan properties: `RLOC16`, `RouterId` and `PreferredRouterId`
* ncp-spinel: Add child table and last status logs
* ncp-spinel: Add addresses for on-mesh SLAAC prefixes.
* ncp-spinel: Add ON_MESH_NETs and LOCAL_ROUTs with stable flag set to true
* ncp-plugins: Stop printing out `get_property` debug prints during initialization.
* connman-plugin: Updates to get the plugin compiling on Android
* connman-plugin: Don't include mcheck.h
* build-system: Reintroduce AM_MAINTAINER_MODE
* build-system: Include a stub copy of boost for systems that don't have it. (#129)
* build-system: Don't quote AC_MSG_ERROR
* build-system: Address M4 quoting issue
* build-system: Add missing -module LDFLAG for ConnMan plug-in (#71)
* build-system: Add automatic generation of Android.mk files
* assert-macros: Have `check_noerr()` actually print out the error code.
* any-to: Allow any_to_string to always work.
* SuperSocket: Only try to lock actual files.
* IPv6Helpers: General cleanup. Introduced `make_slaac_addr_from_eui64()`.
* INSTALL: Clarified and improved installation instructions. (#4)
* Avoid calling functions that aren't async-signal-safe from signal handlers

commit	0097803c69ff07b1b5c9eea102b858527c3da23d	[log] [tgz]
author	Robert Quattlebaum <rquattlebaum@nestlabs.com>	Fri Mar 31 20:31:12 2017
committer	Robert Quattlebaum <rquattlebaum@nestlabs.com>	Fri Mar 31 20:33:49 2017
tree	8f7e2d8b716041cf05190388cdd4e16b994d4c0b
parent	7f9bc5e3a4e8f303a059e3f76a3b410c75480ebe [diff]

Update CHANGELOG and bump version to 0.07.01

3 files changed

tree: 8f7e2d8b716041cf05190388cdd4e16b994d4c0b

README.md

wpantund, Userspace WPAN Network Daemon

wpantund is a user-space network interface driver/daemon that provides a native IPv6 network interface to a low-power wireless Network Co-Processor (or NCP). It was written and developed by Nest Labs to make supporting Thread connectivity on Unix-like operating systems more straightforward.

wpantund is designed to marshall all access to the NCP, ensuring that it always remains in a consistent and well-defined state.

This is not an official Google product.

Feature and Architecture Summary

wpantund provides:

... a native IPv6 interface to an NCP.
... a command line interface (wpanctl) for managing and configuring the NCP.
... a DBus API for managing and configuring the NCP.
... a way to reliably manage the power state of the NCP.
... a uniform mechanism for handling NCP firmware updates.

The architecture and design of wpantund has been motivated by the following design goals (in no specific order):

Portability across Unix-like operating systems (currently supports Linux and OS X. BSD support should be fairly trivial to add)
Require few runtime dependencies (DBus, with boost needed when building)
Single-threaded architecture, with heavy use of asynchronous I/O
Power efficiency (0% CPU usage when idle)
Allow management interface to be used by multiple independent applications simultaneously
Allow multiple instances of wpantund to gracefully co-exist on a single machine
Modular, plugin-based architecture (all details for communicating with a specific NCP stack are implemented as plugins)

Note that Windows is not currently supported, but patches are welcome.

The following NCP plugins are provided:

src/ncp-spinel: Supports NCPs that communicate using the Spinel NCP Protocol, used by NCPs running OpenThread
src/ncp-dummy: A dummy NCP plug-in implementation meant to be the starting point for implementing new NCP plug-ins

License

wpantund is open-source software released under the Apache License, Version 2.0. See the file LICENSE for more information.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Conceptual Overview

wpantund is conceptually similar in purpose to the point-to-point daemon (pppd, commonly used on Unix platforms to provide network connectivity via a dial-up modems) except that instead of communicating with a dial-up modem, wpantund is communicating with an NCP.

wpantund communicates with the NCP via an abstraction of a asynchronous stream socket, which could be any of the following:

A real serial port (UART) connected to the NCP (preferably with hardware flow control)
The stdin and stdout from a subprocess (for supporting SPI interfaces using a translator program or debugging virtual stacks)
A TCP socket (for debugging, not recommended for production)

Unlike a dial-up modem, NCPs often have a rich management interface for performing operations, such as forming a network, joining a network, scanning for nearby networks, etc. To perform these operations, wpantund includes a command line utility called wpanctl. Applications that need to directly configure the network interface can also communicate directly with wpantund using its DBus API.

To expose a native IPv6 network interface to the host operating system, wpantund uses the tun driver on Linux and the utun driver on OS X. On Linux, the default name for the interface is wpan0. On OS X, the default name is utun0.

Usage Overview

The behavior of wpantund is determined by its configuration parameters, which may be specified in a configuration file (typically /etc/wpantund.conf) or at the command line. A typical configuration file might look like that shown below. For a more thorough explanation of available configuration parameters, see the included example.

# Try to name the network interface `wpan0`.
# If not possible, a different name will be used.
Config:TUN:InterfaceName      "wpan0"

# The pathname of the socket used to communicate
# with the NCP.
Config:NCP:SocketPath         "/dev/ttyUSB0"

# The name of the driver plugin to use. The chosen
# plugin must support the NCP you are trying to use.
Config:NCP:DriverName         "spinel"

# Drop root privileges after opening all sockets
Config:Daemon:PrivDropToUser  "nobody"

# Use a CCA Threshold of -70db
NCP:CCAThreshold              "-70"

When up and running, you can use wpanctl to check the status of the interface and perform various management operations. For example, to check the general status of an interface:

$ sudo wpanctl status
wpan0 => [
    "NCP:State" => "offline"
    "Daemon:Enabled" => true
    "NCP:Version" => "OPENTHREAD/g1651a47; May 23 2016 17:23:24"
    "Daemon:Version" => "0.07.00 (May 23 2016 12:58:54)"
    "Config:NCP:DriverName" => "spinel"
    "NCP:HardwareAddress" => [F1D92A82C8D8FE43]
]

Here we see that the NCP is in the offline state along with a few additional bits of information such as the version of the NCP and its hardware address. From here we can easily form a new network:

$ sudo wpanctl form "wpantund-testnet"
Forming WPAN "wpantund-testnet" as node type router
Successfully formed!
$

Now if we check the status, we will see more information:

$ sudo wpanctl status
wpan0 => [
    "NCP:State" => "associated"
    "Daemon:Enabled" => true
    "NCP:Version" => "OPENTHREAD/g1651a47; May 23 2016 17:23:24"
    "Daemon:Version" => "0.07.00 (May 23 2016 12:58:54)"
    "Config:NCP:DriverName" => "spinel"
    "NCP:HardwareAddress" => [F1D92A82C8D8FE43]
    "NCP:Channel" => 23
    "Network:NodeType" => "leader"
    "Network:Name" => "wpantund-testnet"
    "Network:XPANID" => 0x09717AEF221F66FB
    "Network:PANID" => 0xBFCD
    "IPv6:LinkLocalAddress" => "fe80::f3d9:2a82:c8d8:fe43"
    "IPv6:MeshLocalAddress" => "fd09:717a:ef22::9a5d:5d1e:5527:5fc8"
    "IPv6:MeshLocalPrefix" => "fd09:717a:ef22::/64"
]
$ ifconfig wpan0
wpan0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1280
    inet6 fe80::f3d9:2a82:c8d8:fe43%wpan0 prefixlen 10 scopeid 0x15
    inet6 fd09:717a:ef22::9a5d:5d1e:5527:5fc8 prefixlen 64

If compiled with libreadline or libedit, wpanctl supports an convenient interactive console. All commands support online help: type help to get a list of supported commands, or add -h to a command to get help with that specific command.

For more information, see the wiki: https://github.com/openthread/wpantund/wiki

Support

Submit bugs and feature requests to issue tracker. We use the following mailing lists for discussion and announcements:

wpantund-announce - Official Anouncements About wpantund
wpantund-users - wpantund User Discussion Group
wpantund-devel - wpantund Developer Discussion Group

Authors and Contributors

The following people have significantly contributed to the design and development of wpantund:

Robert Quattlebaum
Marcin Szczodrak
Vaas Krishnamurthy
Arjuna Siva
Abtin Keshavarzian

If you would like to contribute to this project, please read CONTRIBUTING.md first.