Improve developer documentation in README.md

Author: agners

README.md

@@ -17,15 +17,40 @@ open source [Matter/Project CHIP repository][project-chip].
 The project offers a IPython based REPL for testing/exploring. The REPL is also
 available as [Python CHIP Controller REPL Add-on][chip-controller-repl-add-on].
 
-### Run from the source tree
+### Prepare venv for the Matter Server
+
+This Python Matter Server needs the CHIP Controller Python libraries. The CHIP
+Controller Python libraries come with the complete Matter SDK (CHIP stack)
+as a native C++ library. The CHIP Controller Python is not available on pip,
+and, because it comes with a native C++ library, is a platform dependent
+library. The Matter SDK allows to build a Python wheel for your platform.
+
+To build the Python CHIP Controller follow the building instructions available
+at [docs/guides/python_chip_controller_building.md][python-chip-building].
+
+Note the essential command is `scripts/build_python.sh -m platform -i separate`.
+It builds the library in `out/python_lib/`, and creates a venv for you in
+`out/python_env/`. If you update the Matter SDK git repository, make sure to
+run this command again to rebuild the library.
+
+If you already compiled the CHIP Controller Python libraries previously, you
+can activate the Python virtual environment using:
 
-The Server needs to be run in a Python environment where the Python CHIP
-Controller is installed. E.g.
 
 ```
 source ../connectedhomeip/out/python_env/bin/activate
 ```
 
+Note: There is a bug with Apple M1 based systems: Pigweed currently uses Python
+x86-64 via Rosetta. That causes problems when trying to build the Python
+CHIP Controller. There are work arounds documented in [GitHub issue #19134](https://github.com/project-chip/connectedhomeip/issues/19134).
+Make sure to not use `-i separate` and setup the venv separately as well.
+
+### Run from the source tree
+
+The Server needs to be run in a Python environment where the Python CHIP
+Controller is installed. E.g.
+
 Also make sure that the default storage location is present:
 ```
 mkdir $HOME/.chip-storage/
@@ -37,7 +62,9 @@ With the following command the server can be run directly from the source tree.
 python3 -m matter_server.server
 ```
 
-_On MacOs you will have to run above command with 'sudo' as it requires to interact with BLE._
+_On macOS you will have to run above command with 'sudo' as it requires to interact with BLE._
+
+_On Linux, make sure Bluetooth (bluez) is active and enabled before starting onboarding._
 
 The client does not need to be run in the Python CHIP Controller environment. It
 can be run from the source tree using:
@@ -48,9 +75,7 @@ python3 -m matter_server.client
 
 ### Build and install
 
-To build the Python CHIP Controller follow the building instructions available
-at [docs/guides/python_chip_controller_building.md][python-chip-building].
-Once you have a working Python CHIP Controller Python environment, switch
+nce you have a working Python CHIP Controller Python environment, switch
 to this repository and install this project as follows:
 
 ```shell