From 4520d8676a415dacd42bd6a6933ff4d7e34c422c Mon Sep 17 00:00:00 2001 From: raiden00pl Date: Tue, 24 Oct 2023 12:24:14 +0200 Subject: [PATCH] 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 +- .../applications/wireless/wapi/index.rst | 9 +- 5 files changed, 327 insertions(+), 14 deletions(-) create mode 100644 Documentation/applications/wireless/btsak/index.rst create mode 100644 Documentation/applications/wireless/i8sak/index.rst 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 help + +info:: + + Command: info + Description: Show Bluetooth driver information + Usage: bt info [-h] + +features:: + + Command: features + Description: Show Bluetooth driver information + Usage: bt features [-h] [le] + Where: le - Selects LE features vs BR/EDR features + +scan:: + + Command: scan + Description: Bluetooth scan commands + Usage: bt scan [-h] + 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 advertise [-h] + 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 security [-h] public|random + Where: - The 6-byte address of the connected peer + - 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 gatt [-h] [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 gatt exchange-mtu [-h] public|random + +mget:: + + Command: mget + Description: Get the pass/fail result of the last GATT 'exchange-mtu' command + Usage: bt gatt mget [-h] + +discover:: + + Command: discover + Description: Initiate discovery + Usage: bt gatt discover [-h] public|random [ []] + +characteristic:: + + Command: characteristic + Description: Initiate characteristics discovery + Usage: bt gatt characteristic [-h] public|random [ []] + +descriptor:: + + Command: descriptor + Description: Initiate characteristics discovery + Usage: bt gatt descriptor [-h] public|random [ []] + +dget:: + + Command: dget + Description: Get the result of the last discovery action + Usage: bt gatt dget [-h] + +read:: + + Command: read + Description: Initiate a GATT read operation. + Usage: bt gatt read [-h] public|random [] + +read-multiple:: + + Command: read-multiple + Description: Initiate a GATT read-multiple operation. + Usage: bt gatt read-multiple [-h] public|random [ []..] + +rget:: + + Command: rget + Description: Get the data resulting from the last read operation + Usage: bt gatt rget [-h] + +write:: + + Command: write + Description: Initiate a GATT write operation. + Usage: bt gatt write [-h] public|random [ []..] + +wget:: + + Command: wget + Description: Get the pass/fail result of the last GATT 'write' command + Usage: bt 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.