This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 4520d8676a415dacd42bd6a6933ff4d7e34c422c
Author: raiden00pl <raide...@railab.me>
AuthorDate: Tue Oct 24 12:24:14 2023 +0200
Documentaion: migrate wireless/readme
---
.../applications/wireless/btsak/index.rst | 147 ++++++++++++++++++
.../applications/wireless/i8sak/index.rst | 172 +++++++++++++++++++++
Documentation/applications/wireless/index.rst | 7 +-
.../applications/wireless/nimble/index.rst | 6 +-
Documentation/applications/wireless/wapi/index.rst | 9 +-
5 files changed, 327 insertions(+), 14 deletions(-)
diff --git a/Documentation/applications/wireless/btsak/index.rst
b/Documentation/applications/wireless/btsak/index.rst
new file mode 100644
index 0000000000..ea59b11126
--- /dev/null
+++ b/Documentation/applications/wireless/btsak/index.rst
@@ -0,0 +1,147 @@
+====================================
+``btsak`` Bluetooth Swiss Army Knife
+====================================
+
+Commands
+--------
+
+help::
+
+ Command: help
+ Description: Should overall command help
+ Usage: bt <ifname> help
+
+info::
+
+ Command: info
+ Description: Show Bluetooth driver information
+ Usage: bt <ifname> info [-h]
+
+features::
+
+ Command: features
+ Description: Show Bluetooth driver information
+ Usage: bt <ifname> features [-h] [le]
+ Where: le - Selects LE features vs BR/EDR features
+
+scan::
+
+ Command: scan
+ Description: Bluetooth scan commands
+ Usage: bt <ifname> scan [-h] <start [-d]|get|stop>
+ Where: start - Starts scanning. The -d option enables duplicate
+ filtering.
+ get - Shows new accumulated scan results
+ stop - Stops scanning
+
+advertise::
+
+ Command: advertise
+ Description: Bluetooth advertise commands
+ Usage: bt <ifname> advertise [-h] <start|stop>
+ Where: start - Starts advertising
+ stop - Stops advertising
+
+security::
+
+ Command: security
+ Description: Enable security (encryption) for a connection:
+ If device is paired, key encryption will be enabled. If
+ the link is already encrypted with sufficiently strong
+ key this command does nothing.
+
+ If the device is not paired pairing will be initiated. If
+ the device is paired and keys are too weak but input output
+ capabilities allow for strong enough keys pairing will be
+ initiated.
+
+ This command may return error if required level of security
+ is not possible to achieve due to local or remote device
+ limitation (eg input output capabilities).
+
+bt::
+
+ Usage: bt <ifname> security [-h] <addr> public|random <level>
+ Where: <addr> - The 6-byte address of the connected peer
+ <level> - Security level, on of:
+
+ low - No encryption and no authentication
+ medium - Encryption and no authentication (no MITM)
+ high - Encryption and authentication (MITM)
+ fips - Authenticated LE secure connections and encryption
+
+gatt::
+
+ Command: gatt
+ Description: Generic Attribute (GATT) commands
+ Usage: bt <ifname> gatt [-h] <cmd> [option [option [option...]]]
+ Where: See "GATT Commands" below
+
+GATT Commands
+-------------
+
+exchange-mtu::
+
+ Command: exchange-mtu
+ Description: Set MTU to out maximum and negotiate MTU with peer
+ Usage: bt <ifname> gatt exchange-mtu [-h] <addr> public|random
+
+mget::
+
+ Command: mget
+ Description: Get the pass/fail result of the last GATT 'exchange-mtu'
command
+ Usage: bt <ifname> gatt mget [-h]
+
+discover::
+
+ Command: discover
+ Description: Initiate discovery
+ Usage: bt <ifname> gatt discover [-h] <addr> public|random <uuid16>
[<start> [<end>]]
+
+characteristic::
+
+ Command: characteristic
+ Description: Initiate characteristics discovery
+ Usage: bt <ifname> gatt characteristic [-h] <addr> public|random
[<start> [<end>]]
+
+descriptor::
+
+ Command: descriptor
+ Description: Initiate characteristics discovery
+ Usage: bt <ifname> gatt descriptor [-h] <addr> public|random [<start>
[<end>]]
+
+dget::
+
+ Command: dget
+ Description: Get the result of the last discovery action
+ Usage: bt <ifname> gatt dget [-h]
+
+read::
+
+ Command: read
+ Description: Initiate a GATT read operation.
+ Usage: bt <ifname> gatt read [-h] <addr> public|random <handle>
[<offset>]
+
+read-multiple::
+
+ Command: read-multiple
+ Description: Initiate a GATT read-multiple operation.
+ Usage: bt <ifname> gatt read-multiple [-h] <addr> public|random
<handle> [<handle> [<handle>]..]
+
+rget::
+
+ Command: rget
+ Description: Get the data resulting from the last read operation
+ Usage: bt <ifname> gatt rget [-h]
+
+write::
+
+ Command: write
+ Description: Initiate a GATT write operation.
+ Usage: bt <ifname> gatt write [-h] <addr> public|random <handle>
<byte> [<byte> [<byte>]..]
+
+wget::
+
+ Command: wget
+ Description: Get the pass/fail result of the last GATT 'write' command
+ Usage: bt <ifname> gatt wget [-h]
diff --git a/Documentation/applications/wireless/i8sak/index.rst
b/Documentation/applications/wireless/i8sak/index.rst
new file mode 100644
index 0000000000..22342e72ec
--- /dev/null
+++ b/Documentation/applications/wireless/i8sak/index.rst
@@ -0,0 +1,172 @@
+==================================================
+``i8sak`` or ``i8`` IEEE 802.15.4 Swiss Army Knife
+==================================================
+
+Description
+-----------
+
+The i8sak app is a useful CLI for testing various IEEE 802.15.4 functionality.
+It also serves as a starting place for learning how to interface with the NuttX
+IEEE 802.15.4 MAC layer.
+
+The i8sak CLI can be used to manipulate multiple MAC layer networks at once.
+Both a MAC character driver interface and a network interface using sockets are
+supported. The MAC character driver is used in cases where networking is not
+enabled and you want your application to use IEEE 802.15.4 directly. In most
+cases however, you will probably be using 6LoWPAN networking support and
+therefore, the MAC can be controlled directly from the socket interface rather
+than the MAC character driver. IEEE 802.15.4 MAC character drivers show up in
+NuttX as ``/dev/ieeeN`` by default.
+
+When you invoke the first call to i8sak with a specified interface name, it
+creates an i8sak instance and launches a daemon to handle processing work. The
+instance is considered sticky, so it is possible to run ``i8 /dev/ieee0`` or
``i8
+wpan0`` at the beginning of a session and then can exclude the interface name
+from all future calls. The number of i8sak instances supported is controllable
+through menuconfig.
+
+The ``i8sak`` app has many settings that can be configured. Most options are
+_sticky_, meaning, if you set the endpoint short address once, any future
+operation using the endpoint short address can default to the previously used
+address. This is particularly useful to keep the command lengths down.
+
+## How To Use
+
+The i8sak app has a series of CLI functions that can be invoked. The default
+i8sak command is ``i8`` to make things quick and easy to type.
+
+In my test setup I have 2 Clicker2-STM32 boards from MikroElektronika, with the
+BEE-click (MRF24J40) radios. Choose one device to be the PAN Coordinator. We'll
+refer to that as device A.
+
+On that device, run::
+
+ i8 /dev/ieee0 startpan cd:ab
+
+This will tell the MAC layer that it should now act as a PAN coordinator using
+PAN ID CD:AB. For now, this function assumes that we are operating a non-beacon
+enabled PAN, since, as of this writing, beacon-enabled networks are unfinished.
+
+Next, on the same device, run::
+
+ i8 acceptassoc
+
+Notice in the second command, we did not use the devname, again, that is
+_sticky_ so unless we are switching back and forth between character drivers,
we
+can just use it once.
+
+The acceptassoc command, without any arguments, informs the ``i8sak`` instance
to
+accept all association requests. The acceptassoc command also allows you to
only
+accept requests from a single device by specifying the extended address with
+option ``-e``.
+
+For instance::
+
+ i8 acceptassoc -e DEADBEEF00FADE0B
+
+But for this example, let's just use the command with no arguments.
+
+Now, the second device will act as an endpoint device. The i8sak instance
+defaults to being in endpoint mode. Let's refer to the second device as device
+``B``.
+
+On device B, run::
+
+ i8 /dev/ieee0 assoc
+
+This command attempts to associate with the node at the configured endpoint
+address. If everything is setup correctly, device A should have log information
+saying that a device tried to associate and that it accepted the association.
On
+device ``B``, the console should show that the association request was
successful.
+With all default settings, device B should have been allocated a short address
+of ``0x000B``.
+
+If you are following along with a packet sniffer, you should see something
+similar to the following::
+
+ 1) Association Request
+ Frame Type - CMD
+ Sequence Number - 0
+ Dest. PAN ID - 0xFADE
+ Dest. Address - 0x000A
+ Src. PAN ID - 0xFFFE
+ Src. Address - 0xDEADBEEF00FADE0C
+ Command Type - Association Request
+
+ 1a) ACK
+ Frame Type - ACK
+ Sequence Number - 0
+
+ 2) Data Request
+ Frame Type - CMD
+ Sequence Number - 1
+ Dest. PAN ID - 0xFADE
+ Dest. Address - 0x000A
+ Src. PAN ID - 0xFFFE
+ Src. Address - 0xDEADBEEF00FADE0C
+ Command Type - Data Request
+
+ 2a) ACK
+ Frame Type - ACK
+ Sequence Number - 1
+
+ 3) Association Response
+ Frame Type - CMD
+ Sequence Number - 0
+ Dest. PAN ID - 0xFADE
+ Dest. Address - 0xDEADBEEF00FADE0C
+ Src. Address - 0xDEADBEEF00FADE0A
+ Command Type - Association Response
+ Assigned SADDR - 0x000C
+ Assoc Status - Successful
+
+ 3a) ACK
+ Frame Type - ACK
+ Sequence Number - 0
+
+The default endpoint address can be configured via Kconfig or set dynamically
+using the ``set`` command.
+
+Here is how to set the endpoint short address::
+
+ i8 set ep_saddr 0a:00
+
+When setting the address, it's important to make sure the endpoint addressing
+mode is configured the way you want: Use ``s`` for short addressing or ``e``
for
+extended::
+
+ i8 set ep_addrmode s
+
+Device B has now successfully associated with device A. If you want to send
data
+from device B to device A, run the following on device B::
+
+ i8 tx ABCDEF
+
+This will immediately (not actually immediate, transaction is sent using CSMA)
+send the frame to device A with frame payload ``0xABCDEF``
+
+Sending data from device A to device B is different. In IEEE 802.15.4, frames
+must be extracted from the coordinator. To prepare the frame, run the following
+command on device A::
+
+ i8 tx AB
+
+Because the devmode is PAN Coordinator, the ``i8sak`` app knows to send the
data
+as an indirect transaction. If you were running the ``i8sak`` app on a device
that
+is a coordinator, but not the PAN coordinator, you can force the ``i8sak`` app
to
+send the transaction directly, rather than to the parent coordinator, by using
+the ``-d`` option.
+
+**Note**: Currently, the indirect transaction timeout is disabled. This means
+frames must be extracted or space may run out. This is only for the testing
+phase as it is easier to debug when I am not fighting a timeout. Re-enabling
the
+timeout may effect the behavior of the indirect transaction features in the
+``i8sak`` app.
+
+To extract the data, run the following command on device ``B``::
+
+ i8 poll
+
+This command polls the endpoint (our device A PAN Coordinator in this case) to
+see if there is any data. In the console of device B you should see a Poll
+request status print out.
diff --git a/Documentation/applications/wireless/index.rst
b/Documentation/applications/wireless/index.rst
index 0951a19d0a..bcb2c2ee67 100644
--- a/Documentation/applications/wireless/index.rst
+++ b/Documentation/applications/wireless/index.rst
@@ -4,15 +4,12 @@ Wireless Libraries and NSH Add-Ons
.. toctree::
:glob:
- :maxdepth: 3
+ :maxdepth: 1
:titlesonly:
- wapi/index.rst
- nimble/index.rst
+ */index*
-- btsak - Bluetooth Swiss Army Knife (NuttX BLE Host)
- gs2200m - Telit GS2200M usrsock daemon
-- i8sak - IEEE 802.15.4 Swiss Army Knife
- i8shark - IEEE 802.15.4 Wireshark adapter
- libmac - IEEE 802.15.4 MAC library routines
- ipwan - IEEE 802.15.4 Command Line Tool
diff --git a/Documentation/applications/wireless/nimble/index.rst
b/Documentation/applications/wireless/nimble/index.rst
index f0f825bb71..06ab31a99f 100644
--- a/Documentation/applications/wireless/nimble/index.rst
+++ b/Documentation/applications/wireless/nimble/index.rst
@@ -1,6 +1,6 @@
-========================================
-Apache NimBLE (BLE host-layer) for NuttX
-========================================
+===================================================
+``nimble`` Apache NimBLE (BLE host-layer) for NuttX
+===================================================
This application will build nimBLE stack (host-only) as a library/application
in NuttX.
diff --git a/Documentation/applications/wireless/wapi/index.rst
b/Documentation/applications/wireless/wapi/index.rst
index 0158ca1287..15c3e46006 100644
--- a/Documentation/applications/wireless/wapi/index.rst
+++ b/Documentation/applications/wireless/wapi/index.rst
@@ -1,9 +1,6 @@
-===================
-WAPI (Wireless API)
-===================
-
-WAPI (Wireless API) provides an easy-to-use function set to configure
-wireless network interfaces on a GNU/Linux system, originally.
+============================
+``wapi`` WAPI (Wireless API)
+============================
One can provide use ``wapi`` to connect to Access Points, configure an
Access Point, set Wi-Fi related configurations and get information about it.
