docs: populate installation, boards, contributing, env-setup, run-tests

docs/contributing.rst

@@ -1,4 +1,36 @@
 Contributing
 *************
 
-.. TODO: contribution guidelines.
+We welcome community contributions! If you have a suggestion that would make
+this better, please fork the repo and create a pull request for your changes
+as described below. You can also simply open a feature request issue.
+
+1. `Fork <https://github.com/Infineon/ArduinoCore-zephyr/fork>`_ this repository.
+2. Create your feature branch (``git checkout -b feature/amazing-feature``).
+3. Commit your changes, following the commit title format below.
+4. Push to the branch (``git push origin feature/amazing-feature``).
+5. Open a `pull request <https://github.com/Infineon/ArduinoCore-zephyr/pulls>`_.
+
+Before submitting a pull request, please check the
+`code of conduct <https://github.com/Infineon/ArduinoCore-zephyr/blob/main/CODE_OF_CONDUCT.md>`_.
+
+Commit and PR title format
+============================
+
+Commit titles and PR titles should follow the pattern ``<scope>: <description>``.
+
+Examples of valid titles:
+
+- ``edge: register PSOC Edge E84 board``
+- ``edge: add PSOC Edge E84 variant``
+
+Examples of invalid titles:
+
+- ``Edge support``
+- ``fix issue``
+
+Additionally, the following sections might be helpful for developing and
+testing your contributions:
+
+- :doc:`env-setup`
+- :doc:`run-tests`

docs/env-setup.rst

@@ -1,4 +1,101 @@
 Environment Setup
 *******************
 
-.. TODO: development environment setup instructions.
+.. note::
+   This setup is currently documented for Linux and WSL environments.
+
+Prerequisites
+==============
+
+- Python 3.12 or newer, with ``pip`` and ``venv``.
+- On Ubuntu or other apt-based distributions:
+
+  .. code-block:: bash
+
+     sudo apt install python3-pip python3-setuptools python3-venv \
+       build-essential git cmake ninja-build zstd jq rsync
+
+Clone the repository
+======================
+
+.. code-block:: bash
+
+   git clone https://github.com/Infineon/ArduinoCore-zephyr.git
+   cd ArduinoCore-zephyr
+
+Run the bootstrap script
+==========================
+
+.. code-block:: bash
+
+   ./extra/bootstrap.sh
+
+This downloads Zephyr and the required HALs, installs the Arm toolchain, and
+fetches the required firmware blobs. Allow approximately 15-30 minutes on the
+first run.
+
+Build and flash the loader
+=============================
+
+.. code-block:: bash
+
+   ./extra/build.sh kit_pse84_ai
+   west flash -d build/kit_pse84_ai_pse846gps2dbzc4a_m33
+
+Flashing requires a KitProg3-compatible OpenOCD with the board's interface
+script. If you hit ``Can't find interface/kitprog3.cfg`` or similar errors,
+install `Infineon OpenOCD <https://github.com/Infineon/openocd/releases>`_
+(minimum v5.8.0) and point west at it in ``~/.west/config``:
+
+.. code-block:: ini
+
+   [runner.openocd]
+   openocd = /opt/openocd/bin/openocd
+   openocd_search = /opt/openocd/scripts
+
+Install the Arduino CLI
+==========================
+
+.. code-block:: bash
+
+   mkdir -p ~/.local/bin
+   curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR=~/.local/bin sh
+   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+   source ~/.bashrc
+
+Install the core and tools
+=============================
+
+.. code-block:: bash
+
+   arduino-cli core install infineon:zephyr_pse84 \
+     --additional-urls https://github.com/Infineon/ArduinoCore-zephyr/releases/latest/download/package_infineon_pse84_index.json
+
+Local development
+====================
+
+To compile against your local checkout instead of the released core,
+symlink it into the sketchbook's hardware folder:
+
+.. code-block:: bash
+
+   mkdir -p ~/Arduino/hardware/infineon
+   ln -s ~/ArduinoCore-zephyr ~/Arduino/hardware/infineon/zephyr_pse84
+
+The sketchbook hardware folder takes precedence over the installed package
+for the same FQBN. Remove the symlink to revert to the released core.
+
+Compile and upload
+======================
+
+Uploading requires permission to open the serial port:
+
+.. code-block:: bash
+
+   sudo usermod -aG dialout "$USER"
+
+.. code-block:: bash
+
+   arduino-cli sketch new MySketch
+   arduino-cli compile -b infineon:zephyr_pse84:kit_pse84_ai MySketch
+   arduino-cli upload -b infineon:zephyr_pse84:kit_pse84_ai -p /dev/ttyACM0 MySketch

docs/hw-platforms.rst

@@ -1,9 +1,49 @@
 Supported Boards
 ******************
 
-.. TODO: list supported boards, one section per board.
-
 KIT-PSE84-AI
 =============
 
-.. TODO
+The `Infineon KIT-PSE84-AI <https://www.infineon.com/evaluation-board/kit-pse84-ai>`_
+(PSOC™ Edge E84) is the first supported board for the PSOC™ Edge family.
+
+- FQBN: ``infineon:zephyr_pse84:kit_pse84_ai``
+- Silicon: PSE846GPS2DBZC4A
+
+Pinout Diagram
+---------------
+
+.. image:: img/KIT_PSE84_AI_Pinout.svg
+   :width: 400
+
+.. TODO: add a back-side pinout diagram (with Arduino pin numbers) for the analog pins.
+   Once a complete, labeled pinout diagram exists for both sides, consider
+   trimming or removing the Macros section below in favor of the diagram.
+
+Macros
+------
+
+For the exact macro definitions, refer to
+``variants/kit_pse84_ai_pse846gps2dbzc4a_m33/variant.h``. General rules:
+
+- Every exposed GPIO pin from the pinout has a macro identical to the
+  documentation name, e.g. ``P17_3``, ``P16_0``, ``P15_3``, etc.
+- Digital pins have a macro in the format ``Dx``, where ``x`` is the index of
+  the Arduino pin in the range [0, 47], e.g. ``D0``, ``D15``, ``D47``, etc.
+- Analog pins have a macro in the format ``Ax``, where ``x`` is the index of
+  the Arduino pin in the range [0, 15], e.g. ``A0``, ``A1``, ``A15``, etc.
+- Onboard LED and button macros are:
+
+  - ``LED_BUILTIN`` / ``LED_BUILTIN_1``: the primary onboard LED (same pin,
+    two names). ``LED_BUILTIN_2`` is the second, distinct onboard LED.
+  - ``LED_BUILTIN_ACTIVE``: the logic level that turns an onboard LED on.
+  - ``LED_RED`` / ``LED_GREEN`` / ``LED_BLUE``: the individual channels of
+    the onboard RGB LED.
+  - ``BTN_BUILTIN``: the onboard user button (``SW1``).
+
+- Expansion header pins include the macros as printed on the board:
+  ``SERIAL_INTx`` where ``x`` is the index in the range [0, 3], e.g.
+  ``SERIAL_INT0``.
+
+.. TODO: document I2C/Wire (SDA, SCL, SDA1, SCL1) and SPI (MOSI, MISO, etc.)
+   macros once verified working on this board.