SWPROT-8953: Docs add Quickstart instructions

.dockerignore

@@ -0,0 +1,33 @@
+# .dockerignore
+Dockerfile
+docker-compose.yml
+
+# .gitignore
+# Temporary files
+*~
+tmp
+# All build folders
+/build*/
+# Visual Studio Code
+.vscode/settings.json
+.vscode/launch.json
+.vscode/*.log
+*.code-workspace
+# JetBrains IDE
+.idea/
+# Cmake Projects in root ###
+compile_commands.json
+# Clangd index
+.clangd/
+.cache/
+# BeyondCompare backup files
+*.orig
+# SonarScanner files
+.scannerwork/
+# Generated debconf files
+applications/*/debconf/config
+# Macos fs igores
+*.DS_Store
+# Other files
+*.swp
+*.gcov

.gitignore

@@ -0,0 +1,29 @@
+# .gitignore
+# Temporary files
+*~
+tmp
+# All build folders
+/build*/
+# Visual Studio Code
+.vscode/settings.json
+.vscode/launch.json
+.vscode/*.log
+*.code-workspace
+# JetBrains IDE
+.idea/
+# Cmake Projects in root ###
+compile_commands.json
+# Clangd index
+.clangd/
+.cache/
+# BeyondCompare backup files
+*.orig
+# SonarScanner files
+.scannerwork/
+# Generated debconf files
+applications/*/debconf/config
+# Macos fs igores
+*.DS_Store
+# Other files
+*.swp
+*.gcov

Dockerfile

@@ -34,5 +34,12 @@ RUN echo "# log: Build" \
   && ./helper.mk \
   && date -u
 
-ENTRYPOINT [ "/usr/local/opt/z-wave-protocol-controller/helper.mk" ]
-CMD [ "help" ]
+RUN echo "# log: Install to system" \
+  && set -x  \
+  && sudo dpkg -i ./build/${project}_*/*.deb \
+  || sudo apt install -f \
+  && sudo apt-get install -y mosquitto \
+  && date -u
+
+ENTRYPOINT [ "/usr/bin/zpc" ]
+CMD [ "--help" ]

README.md

@@ -2,8 +2,9 @@
 
 ## About
 
-Z-Wave-Protocol-Controller is a Linux application to control Z-Wave networks with a Silicon Labs NCP,
-It has grown as part of Unify SDK project and is now maintained as an external project.
+Z-Wave-Protocol-Controller is a Linux application to control Z-Wave
+networks with a Silicon Labs NCP, It has grown as part of Unify SDK
+project and is now maintained as an external project.
 
 ## News
 
@@ -22,6 +23,133 @@ Or relevant sources pages, to get started head to:
 
 ## Quickstart
 
+### Native (Linux) build
+
+The project is CMake based, to prepare the environment,
+have a look at [./helper.mk](helper.mk)'s  details
+for needed steps to setup developer system before using CMake normally.
+
+At the moment stable version of Debian (12) is supported,
+so it should work also in relatives projects (Ubuntu, RaspiOS, WSL2 etc)
+and should be easy to adapt to other distributions.
+
+```sh
+sudo apt-get install -y sudo make git
+
+git clone https://github.com/SiliconLabsSoftware/z-wave-protocol-controller
+cd z-wave-protocol-controller
+
+./helper.mk help
+./helper.mk setup  # To setup developer system (once)
+./helper.mk VERBOSE=1 # Default build tasks verbosely (depends on setup)"
+./helper.mk run # Run entry-point application
+```
+
+It should print zpc's help.
+
+To use it, a Silicon Labs' Z-Wave NCP should be plugged in USB port.
+
+To setup the device zwave_ncp_serial_api_controller application should be flashed using
+[simplicity-studio](https://www.silabs.com/developer-tools/simplicity-studio)
+
+Alternatively demo-applications package can be downloaded from
+[SiliconLabs SDK repository](https://github.com/SiliconLabs/simplicity_sdk/releases)
+and flashed using command-line tool
+[SimplicityCommander](https://www.silabs.com/documents/public/software/SimplicityCommander-Linux.zip)
+.
+
+Then to verify you can check firmware version using zpc:
+
+```sh
+lsusb # Should list the NCP device (WSL users should attach device first)
+serial=$(ls /dev/serial/by-id/usb-Silicon_Labs* | head -n1)
+./helper.mk all run run_args="--zpc.serial=${serial} --zpc.ncp_version"
+# <i> [zpc_ncp_update] chip_serial_api_version: 7.23.1
+```
+
+Then let's interact with ZPC's inbuilt shell without installing it.
+
+```sh
+sudo apt install -y mosquitto # Is a strong runtime dependency
+serial=$(ls /dev/serial/by-id/usb-Silicon_Labs* | head -n1)
+run_args="--zpc.serial=${serial}"
+mapdir="applications/zpc/components/dotdot_mapper/rules"
+run_args="$run_args --mapdir=${mapdir}"
+datastore_file="tmp.db"
+run_args="$run_args --zpc.datastore_file=${datastore_file}"
+cache_path="tmp"
+run_args="$run_args --zpc.ota.cache_path=${cache_path}"
+mkdir -p ${cache_path}
+./helper.mk run run_args="$run_args"
+
+
+ZPC>help
+==================================================
+Unify Command line interface Help:
+==================================================
+(...)
+exit  :Exit the application
+(...)
+zwave_home_id Print Z-Wave Home ID
+(...)
+zwave_add_node  :Add a Z-Wave node to the network
+(...)
+zwave_set_default Reset Z-Wave network
+(...)
+ZPC> zwave_home_id
+Z-Wave Home ID:
+1BADC0DE
+ZPC> zwave_add_node
+(...)
+```
+
+Set endnode to learn mode and the controller should see it:
+
+```sh
+(...)
+Please verify the DSK and insert the missing part (first 5 digits)
+Usage: zwave_accept_dsk <insert the first two byte of the DSK in [decimal]>
+ZPC> zwave_accept_dsk (...)
+```
+
+Then you will have to learn how to use couple of shell commands
+"attribute_store_log" and "attribute_store_set_desired",
+as explained in the reference documentation.
+
+```sh
+ZPC>attribute_store_log
+(...)
+ZPC>attribute_store_log_search OnOff
+(...)
+│   │   │   │───(110) ZCL OnOff OnOff .....................................      0
+(...)
+ZPC>attribute_store_set_desired 110,1
+(...)
+```
+
+### More
+
+Refer to [./doc](doc) for more (using shell, MQTT, WebApp etc).
+
+
+### Docker build
+
+The fastest (less than 20min) way to build z-wave-protocol-controller from scratch
+is to delegate all tasks to docker.
+
+```sh
+docker build https://github.com/SiliconLabsSoftware/z-wave-protocol-controller.git#ver_1.7.0
+```
+
+This one-liner will do download latest release, setup environment, build, test, package...
+
+Also a docker-compose file is provided to start ZPC and use it along a MQTT client
+(eg:
+[mosquitto-clients](https://github.com/eclipse-mosquitto/mosquitto/)
+).
+
+Power users might prefer to work in sources tree in a native GNU/Linux
+environment as explained above.
 
 ## Contributing
 

docker-compose.yml

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+# SPDX-License-Identifier: ZLib
+
+version: "2"
+
+services:
+  broker:
+    image: eclipse-mosquitto:1.5.9
+    ports:
+      - '1883:1883'
+    command: mosquitto
+    restart: unless-stopped
+
+  zpc:
+    build: .
+    command: run --mqtt.host=broker
+    devices:
+      - ${DEVICE:-/dev/ttyACM0}:/dev/ttyUSB0
+    depends_on:
+      - broker
+    restart: on-failure

docker/host_dependencies.apt

@@ -12,7 +12,6 @@ git                             // cmake. download gecko_skc and cpc-deamon
 git-lfs                         // cmake. download gecko_skc and cpc-deamon
 graphviz                        // For docs generation
 lcov							// code coverage report (for local code coverage report)
-libasound2                      // ZAP generation
 libgbm1                         // ZAP generation
 ninja-build                     // Build system
 nlohmann-json3-dev              // ZigPC, ZPC, testframework, uic_dotdot_mqtt, uic_smartstart_management. Read JSON from a file.

helper.mk

@@ -16,7 +16,7 @@ url?=https://github.com/SiliconLabsSoftware/z-wave-protocol-controller
 # https://gitlab.kitware.com/cmake/cmake/-/issues/22813#note_1620373
 project_test_dir?=applications
 project_docs_api_target?=zpc_doxygen
-version?=$(shell git describe --tags || echo "0")
+version?=$(shell git describe --tags --always 2> /dev/null || echo "0")
 
 # Allow overloading from env if needed
 # VERBOSE?=1
@@ -34,7 +34,7 @@ sudo?=sudo
 debian_codename?=bookworm
 
 packages?=cmake ninja-build build-essential python3-full ruby clang
-packages+=git-lfs unp time file
+packages+=git-lfs unp time file usbutils bsdutils
 packages+=nlohmann-json3-dev
 # TODO: remove for offline build
 packages+=curl wget python3-pip
@@ -92,14 +92,15 @@ cmake_options+=-DCARGO_TARGET_TRIPLE="${CARGO_TARGET_TRIPLE}"
 export CMAKE_TARGET_TRIPLE
 endif
 
+run_file?=${build_dir}/applications/zpc/zpc
 
 help: ./helper.mk
 	@echo "# ${project}: ${url}"
 	@echo "#"
 	@echo "# Usage:"
 	@echo "#  ${<D}/${<F} setup # To setup developer system (once)"
 	@echo "#  ${<D}/${<F} VERBOSE=1 # Default build tasks verbosely (depends on setup)"
-	@echo "#  ${<D}/${<F} # For more info"
+	@echo "#  ${<D}/${<F} help/all # For more info"
 	@echo "#"
 
 help/all: README.md NEWS.md
@@ -226,14 +227,17 @@ ${build_dir}/CMakeCache.txt: CMakeLists.txt
 	cmake ${cmake_options}
 
 all: ${build_dir}/CMakeCache.txt
-	cmake --build ${<D} \
-		|| cat ${build_dir}/CMakeFiles/CMakeOutput.log
+#	cmake --build ${<D} \
+#		|| cat ${build_dir}/CMakeFiles/CMakeOutput.log
 	cmake --build ${<D}
 .PHONY: all
 
 ${build_dir}/%: all
 	file -E "$@"
 
+${build_dir}: ${build_dir}/CMakeCache.txt
+	file -E "$<"
+
 test: ${build_dir}
 	ctest --test-dir ${<}/${project_test_dir}
 
@@ -260,6 +264,10 @@ prepare: git/prepare
 all/default: configure prepare all test dist
 	@date -u
 
+run_args?=--help
+run:
+	file -E ${run_file}
+	${run_file} ${run_args}
 
 ### @rootfs is faster than docker for env check
 
@@ -312,7 +320,7 @@ docker_url?=${url}.git\#${docker_branch}
 docker/%: Dockerfile
 	time docker run "${project}:latest" -C "${docker_workdir}" "${@F}"
 
-test/docker: distclean prepare/docker docker/help docker/test
+test/docker: distclean prepare/docker docker/help docker/test docker/run
 	@echo "# ${project}: log: $@: done: $^"
 
 test/docker/build: