Add a README.md for Windows (#895)

* Initial readme changes * Update image
2026-08-11 13:17:48 +00:00 · 2016-10-27 13:58:55 -07:00
parent b385229ece
commit 17836de1fe
2 changed files with 115 additions and 0 deletions
@@ -0,0 +1,115 @@
+# 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.
+
+## 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
+
+![Windows Architecture](../../../doc/images/windows_design.png)
+
+This design allows for support of both simple radio devices and devices running the complete
+OpenThread stack.
+
+### otApi.dll ###
+
+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.
+
+### otLwf.sys ###
+
+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.
+
+`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.
+
+In Full Stack mode, `otLwf.sys` hosts the OpenThread core library and manages serializing all Windows
+networking inputs to the OpenThread APIs. It maintains one dedicated worker thread for running all
+OpenThread related logic, including IOCTL commands, data packets, and basic OpenThread processing logic.
+`otLwf.sys` uses [OID][oid]s to send control path commands (channel, panid, etc.) and [NBL][nbl]s to send and
+receive the 802.15.4 data packets to/from the miniport. The miniport then passes this information, in the
+proper format, off to the radio device.
+
+In Tunnel mode, `otLwf.sys` mainly just manages the serialization of Windows networking inputs to 
+Spinel commands (and back). The Spinel commands are passed down (in [NBL][nbl]s) to the miniport which will then pass
+the commands (correctly encoded) to whatever device is externally connected.
+
+### 802.15.4 PHY Miniport ###
+
+This is the component responsible for taking the [OID][oid]s and [NBL][nbl]s from `otLwf.sys` and sending the
+information down to the matching 802.15.4 PHY Device, in the proper format. In other words, it's job is mainly
+handling the arrival/removal of the physical device and serialization of the info in the proper format for
+the device it's paired with.
+
+### Thread Miniport ###
+
+This is the component for taking the [NBL][nbl]s, containing Spinel commands, from `otLwf.sys` and sending them
+down to the matching OpenThread (NCP) Device. Again, like the PHY miniport, it's job is handling device arrival/removal
+and command serialization.
+
+### 802.15.4 PHY Device ###
+
+This is a 'simple' device, exposing a mostly PHY layer interface (with a few MAC layer constructs).
+
+### OpenThread (NCP) Device ###
+
+This is a 'full solution' device, that exposes the entire OpenThread interface via NCP.
+
+## Build ##
+
+Open the Visual Studio Solution `openthread.sln` under `etc\visual-studio` and then pick the
+configuration and platform you wish to build for. For instance, `Release` and `x64`. Build
+the whole solution (F6). This will output the files here:
+
+```
+build\bin\<platform>\<configuration>
+```
+
+## Install ##
+
+### Filter Driver ###
+
+1. Copy the following files to a temporary location on the target machine:
+
+```
+build\bin\<platform>\<configuration>\sys\otLwf.cer
+build\bin\<platform>\<configuration>\sys\otLwf\otLwf.cat
+build\bin\<platform>\<configuration>\sys\otLwf\otLwf.inf
+build\bin\<platform>\<configuration>\sys\otLwf\otLwf.sys
+```
+
+2. Open an admin command prompt in the location of the temporary files.
+
+3. Install the certificate to the root and TrustedPublisher store by running:
+
+```
+certutil -addstore root otLwf.cer
+certutil -addstore TrustedPublisher otLwf.cer
+```
+
+4. Install the driver by running:
+
+```
+netcfg.exe -v -l otlwf.inf -c s -i otLwf
+```
+
+### Miniport Driver ###
+
+`TODO`
+
+## Controlling OpenThread from an Application ##
+
+`TODO`
+