From 4ef65c1ccf0f0f58139b4b0050aaf3f87b1be8e2 Mon Sep 17 00:00:00 2001
From: Yakun Xu <xyk@google.com>
Date: Thu, 13 Sep 2018 14:27:03 +0800
Subject: [PATCH] [posix-app] add README for posix-app (#3052)

---
 src/posix/README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 src/posix/README.md

diff --git a/src/posix/README.md b/src/posix/README.md
new file mode 100644
index 000000000..5ce699ba5
--- /dev/null
+++ b/src/posix/README.md
@@ -0,0 +1,84 @@
+OpenThread POSIX app
+====================
+
+OpenThread supports running its core on POSIX and transmits radio frames through a radio transceiver.
+
+Currently most platforms in [examples/platforms](../../examples/platforms) support transceiver mode.
+
+The figure below shows the architecture of OpenThread running in transceiver mode.
+
+```
++-------------------------+
+|     MLE TMF UDP IP      |
+|  MeshForwarder 6LoWPAN  |
+| _ _ _ _ _ _ _ _ _ _ _ _ |      spinel         +------------------+
+|    OpenThread Core      | <---------------->  | OpenThread Radio |
++-------------------------+     UART|SPI        +------------------+
+         POSIX                                          Chip
+```
+
+Build
+-----
+
+```sh
+# build core for POSIX
+make -f src/posix/Makefile-posix
+# build transceiver, where xxxx is the platform name, such as cc2538, nrf52840 and so on
+make -f examples/Makefile-xxxx
+```
+
+Test
+----
+
+**NOTE** Assuming the build system is 64bit Linux, you can use the normal OpenThread CLI as described in the [command line document](../../src/cli/README.md).
+You can also perform radio diagnostics using the command [diag](../../src/diag/README.md).
+
+### With Simulation
+
+```sh
+make -f examples/Makefile-posix
+./output/posix/x86_64-unknown-linux-gnu/bin/ot-cli ./output/x86_64-unknown-linux-gnu/bin/ot-ncp-radio 1
+```
+
+### With Real Device
+
+#### nRF52840
+
+```sh
+# without USB=1 may result in failure for serial port issue
+make -f examples/Makefile-nrf52840 USB=1
+arm-none-eabi-objcopy -O ihex output/nrf52840/bin/ot-ncp-radio ot-ncp-radio.hex
+nrfjprog -f nrf52 --chiperase --reset --program ot-ncp-radio.hex
+# plug the CDC serial USB port
+./output/posix/x86_64-unknown-linux-gnu/bin/ot-cli /dev/ttyACM0 '115200 raw -echo'
+```
+
+#### CC2538
+
+```sh
+make -f examples/Makefile-cc2538
+arm-none-eabi-objcopy -O binary output/cc2538/bin/ot-ncp-radio ot-ncp-radio.bin
+# see https://github.com/JelmerT/cc2538-bsl
+python cc2538-bsl/cc2538-bsl.py -b 460800 -e -w -v -p /dev/ttyUSB0 ot-ncp-radio.bin
+./output/posix/x86_64-unknown-linux-gnu/bin/ot-cli /dev/ttyUSB0 '115200 raw -echo'
+```
+
+Wpantund Support
+----------------
+
+**NOTE** Assuming the build system is 64bit Linux and *wpantund* is already installed and **stopped**.
+
+### With Simulation
+
+```sh
+sudo wpantund -s 'system:./output/posix/x86_64-unknown-linux-gnu/bin/ot-ncp ./output/x86_64-unknown-linux-gnu/bin/ot-ncp-radio 1'
+```
+
+### With Real Device
+
+```sh
+# nRF52840
+sudo wpantund -s 'system:./output/posix/x86_64-unknown-linux-gnu/bin/ot-ncp /dev/ttyACM0 "115200 raw -echo"'
+# CC2538
+sudo wpantund -s 'system:./output/posix/x86_64-unknown-linux-gnu/bin/ot-ncp /dev/ttyUSB0 "115200 raw -echo"'
+```