diff --git a/samples/bluetooth/ipsp/README.rst b/samples/bluetooth/ipsp/README.rst index 0f63378cc8b..aceec33a897 100644 --- a/samples/bluetooth/ipsp/README.rst +++ b/samples/bluetooth/ipsp/README.rst @@ -19,22 +19,164 @@ Testing with a Linux host ========================= To test IPSP please take a look at samples/net/README, in addition to running -echo-client you must enable 6LowPAN module in Linux with the -following commands: +echo-client you must enable 6LowPAN module in Linux with the following commands +(as root): .. code-block:: console - $ modprobe bluetooth_6lowpan - $ echo 1 > /sys/kernel/debug/bluetooth/6lowpan_enable + # modprobe bluetooth_6lowpan + # echo 1 > /sys/kernel/debug/bluetooth/6lowpan_enable -Then to connect: +If you connected your board to a UART console, you will see an output similar to +(may vary slightly by application and Zephyr versions): .. code-block:: console - $ echo "connect " > /sys/kernel/debug/bluetooth/6lowpan_control + [bt] [WRN] set_static_addr: Using temporary static random address + [bt] [INF] show_dev_info: Identity: cb:af:14:57:d8:6e (random) + [bt] [INF] show_dev_info: HCI: version 5.0 (0x09) revision 0x0000, manufacturer 0xffff + [bt] [INF] show_dev_info: LMP: version 5.0 (0x09) subver 0xffff + [bt] [WRN] bt_pub_key_gen: ECC HCI commands not available + [ipsp] [INF] init_app: Run IPSP sample + [ipsp] [INF] listen: Starting to wait -Once connected a dedicated interface will be created, usually bt0, which can -then be used as following: +The output above shows the BLE address assigned to your board for the +current session; the address will be different on subsequent sessions. + +Alternatively, you may scan for your board on the host. The modern way to do +that is using ``bluetoothctl`` utility (included in the recent versions of +BlueZ package) and its ``scan on`` command: + +.. code-block:: console + + $ bluetoothctl + [NEW] Controller A3:24:97:EB:D6:23 ubuntu-0 [default] + [NEW] Device D7:5C:D6:18:14:87 Zephyr + [NEW] Device E1:E7:F9:56:EC:06 Zephyr + [NEW] Device C8:12:C5:08:86:E1 Zephyr + [bluetooth]# scan on + Discovery started + [NEW] Device DC:98:FB:22:CA:3A Zephyr + +When started, ``bluetoothctl`` shows all BLE (and likely, BT/EDR) devices it +knows about. As discussed above, the IPSP uses static random addresses, so +entries for previously connected devices, as shown above, can accumulate and +become stale. You need to be extra careful to find an entry for the active +address. The best approach may be to reset your board after issuing +``scan on`` command. This way it will reinitialize with the BLE address +which will be discovered after the command. + +As an alternative to ``bluetoothctl``, you can use the legacy ``hcitool`` +utility which talks directly to hardware and always shows fresh scan results: + +.. code-block:: console + + $ sudo hcitool lescan + LE Scan ... + CB:AF:14:57:D8:6E (unknown) + CB:AF:14:57:D8:6E Test IPSP node + +After you have found the board's BLE address, connect to the board (as root): + +.. code-block:: console + + # echo "connect " > /sys/kernel/debug/bluetooth/6lowpan_control + +Where ```` is the BLE address and ```` is BLE address type: +1 for public address and 2 for random address. As you can see from +the IPSP sample output above, it uses a static random address. So, with the +sample output above, the command will be: + +.. code-block:: console + + # echo "connect CB:AF:14:57:D8:6E 2" > /sys/kernel/debug/bluetooth/6lowpan_control + +Once connected a dedicated interface will be created, usually bt0. You can verify this +with the following command: + +.. code-block:: console + + # ifconfig + bt0 Link encap:UNSPEC HWaddr F8-2F-A8-FF-FE-EB-6D-8C-00-00-00-00-00-00-00-00 + inet6 addr: fe80::fa2f:a8ff:feeb:6d8c/64 Scope:Link + UP POINTOPOINT RUNNING MULTICAST MTU:1280 Metric:1 + RX packets:2 errors:0 dropped:3 overruns:0 frame:0 + TX packets:6 errors:0 dropped:0 overruns:0 carrier:0 + collisions:0 txqueuelen:1000 + RX bytes:92 (92.0 B) TX bytes:233 (233.0 B) + +As can be seen from the output, only a link-local IPv6 address was assigned +to the interface. + +At this point, you can test IPv6 connectivity (and discover your board's IPv6 +address) by pinging "All local-link nodes" IPv6 address: + +.. code-block:: console + + # ping6 -I bt0 ff02::1 + PING ff02::1(ff02::1) from fe80::fa54:a8ff:feeb:218f bt0: 56 data bytes + 64 bytes from fe80::fa54:a8ff:feeb:218f: icmp_seq=1 ttl=64 time=0.088 ms + 64 bytes from fe80::c9af:14ff:fe57:d86e: icmp_seq=1 ttl=64 time=285 ms (DUP!) + +For each ping packet, both your host and the BLE board send a reply. You +can see the board's reply marked as ``(DUP!)``. You can ping the board +directly with: + +.. code-block:: console + + # ping6 fe80::c9af:14ff:fe57:d86e%bt0 + PING fe80::c9af:14ff:fe57:d86e%bt0(fe80::c9af:14ff:fe57:d86e) 56 data bytes + 64 bytes from fe80::c9af:14ff:fe57:d86e: icmp_seq=1 ttl=64 time=177 ms + 64 bytes from fe80::c9af:14ff:fe57:d86e: icmp_seq=2 ttl=64 time=53.0 ms + +Note that the command uses a "scoped IPv6 address", where the scope is +defined by the networking interface, with ``%bt0`` appended in this case. +A specification like that is an alternative to passing ``-I bt0`` to +``ping6`` (and works with other networking tools like ``telnet``, ``nc``, +``curl``, etc.) + +While we can use a link-local address, it's not very convenient, as it must be +scoped and will change on each run. Instead, the IPSP sample is configured with +``2001:db8::1`` static address and we'll configure the host's interface to +access that address by configuring ``bt0`` with the complementary address +``2001:db8::2``: + +.. code-block:: console + + # ip address add 2001:db8::2/64 dev bt0 + +Now we can ping the board's static address with: + +.. code-block:: console + + # ping6 2001:db8::1 + PING 2001:db8::1(2001:db8::1) 56 data bytes + 64 bytes from 2001:db8::1: icmp_seq=1 ttl=64 time=282 ms + +The IPSP sample includes builtin echo server for UDP and TCP on a port 4242, +which we can test with: + +.. code-block:: console + + $ telnet 2001:db8::1 4242 + Trying 2001:db8::1... + Connected to 2001:db8::1. + Escape character is '^]'. + test + test + test2 + test2 + ^] + telnet> quit + Connection closed. + +In the output above, first ``test`` line was typed, next was echoed back by +the board. Likewise for ``test2``. To quit telnet tool, type Ctrl+], then +"quit" at the prompt. + +As an alternative to using well-known networking tools above, and also to +test both TCP and UDP echo, you can use Zephyr's helper tool in the GitHub +``zephyrproject-rtos/net-tools`` repository: .. code-block:: console