Update docs

Author: christoph2

.readthedocs.yml

@@ -14,6 +14,9 @@ build:
 sphinx:
    configuration: docs/conf.py
 
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+   - pdf
 # Optionally, but recommended,
 # declare the Python requirements required to build your documentation
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html

docs/tutorial.rst

@@ -19,20 +19,25 @@ Arduino quick start
 -------------------
 The repository contains ready-to-use sketches:
 - ``tools/arduino/hello_xcp``: minimal “hello” XCP slave
-- ``tools/arduino/predefined_daq/predefined_daq.ino``: shows predefined DAQ lists
+- ``tools/arduino/predefined_daq/predefined_daq.ino``: shows how-to use predefined DAQ lists
 
 Prerequisites
 ^^^^^^^^^^^^^
 - Arduino IDE or Arduino CLI installed
 - For Ethernet: an Ethernet-capable board/shield (e.g., W5100/W5500) or WiFi board (ESP32)
-- For CAN: a CAN shield (MKR Zero CAN Shield, Seeed Studio CAN Shield, and SparkFun CAN Shield are currently supported).
+- For CAN: a CAN shield (MKR Zero CAN, Seeed Studio CAN, and SparkFun CAN currently supported).
 - Serial SXI over the board’s UART (recommended starting point).
 
 
 1) Choose a transport
 ^^^^^^^^^^^^^^^^^^^^^
-Open the sketch folder (e.g., ``tools/arduino/hello_xcp``) and edit its ``xcp_config.h``.
-Pick exactly one transport and fill the minimal settings.
+Open the sketch folder (e.g., ``tools/arduino/hello_xcp``) and edit its ``xcp_config.h``,
+un-comment the transport you want to use:
+- `#define TP_SXI` for Serial SXI.
+- `#define TP_CAN` for CAN bus.
+- `#define TP_ETHER` for Ethernet.
+
+Now fill the minimal settings:
 
 Ethernet (UDP)
 """"""""""""
@@ -83,9 +88,9 @@ CAN (Classic or FD)
    // Optional broadcast ID
    // #define XCP_ON_CAN_BROADCAST_IDENTIFIER  (0x222)
 
-- Choose your shield with :c:macro:`XCP_CAN_INTERFACE` and, if applicable, the MCP25xx pins.
+- Choose your shield with :c:macro:`XCP_CAN_INTERFACE` (one of `XCP_CAN_IF_SEED_STUDIO_CAN_SHIELD`, `XCP_CAN_IF_SEED_STUDIO_CAN_FD_SHIELD`, `XCP_CAN_IF_MKR_ZERO_CAN_SHIELD`, `XCP_CAN_IF_SPARKFUN_CAN_SHIELD`) and, if applicable, the MCP25xx pins.
 - Classic CAN forces :c:macro:`XCP_MAX_CTO`/``XCP_MAX_DTO`` to 8. With CAN FD, 8..64 is allowed (see :doc:`options`).
-- Optionally require full DLC via :c:macro:`XCP_ON_CAN_MAX_DLC_REQUIRED`.
+- Optionally require max. DLC (i.e. padding) via :c:macro:`XCP_ON_CAN_MAX_DLC_REQUIRED`.
 
 Serial (SXI)
 """""""""""
@@ -101,7 +106,11 @@ Serial (SXI)
    #define XCP_MAX_CTO                      (64)
    #define XCP_MAX_DTO                      (64)
 
-2) Build and upload
+.. note::
+   The parameters `XCP_ON_SXI_BITRATE` and `XCP_ON_SXI_CONFIG` are not relevant for USB-to-USB connections, but there are boards whose RxD/TxD pins are connected
+   to USB-to-serial converters; here the parameters are crucial for successful communication (not to mention real RS232 ports)!
+
+1) Build and upload
 ^^^^^^^^^^^^^^^^^^^
 Using Arduino IDE: open the sketch, select your board/port, then Compile/Upload.
 Using Arduino CLI (example):
@@ -111,8 +120,8 @@ Using Arduino CLI (example):
    arduino-cli compile --fqbn arduino:avr:uno tools/arduino/hello_xcp
    arduino-cli upload  --fqbn arduino:avr:uno -p COM5 tools/arduino/hello_xcp
 
-3) Connect from the host
-^^^^^^^^^^^^^^^^^^^^^^^^
+3) Connect from the client
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 - Ethernet/WiFi: the slave listens on UDP port 5555 by default.
   - Use your preferred XCP master to connect (e.g., commercial tools or open-source clients). Ensure the IP is reachable.
 - CAN: configure your PC CAN interface with matching bit timing/IDs.
@@ -168,11 +177,6 @@ From the repository root:
 
 Then flash the generated UF2 or use your preferred uploader.
 
-3) Connect from the host
-^^^^^^^^^^^^^^^^^^^^^^^^
-- For SXI: connect your host to the Pico’s UART/USB-serial at the configured baud and use an XCP master that supports SXI.
-- For Ethernet (if you add a module and driver): follow the Arduino Ethernet steps for IP/port selection; sizes remain the same.
-
 Further reading
 ---------------
 - Configuration reference: :doc:`options`