Task/thdubois/wsl2 devices doc

.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

@@ -22,6 +22,121 @@ 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 verify you can check firmware version:
+
+```sh
+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
+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}"
+
+sudo apt install -y mosquitto # Is a strong runtime dependency
+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
+(...)
+```
+
+### WSL2 build
+
+How to use a z-wave controller with ZPC running in WSL2 ?
+
+You can use this [script](./scripts/wslusb.ps1).
+
+Start by installing the usbipd service as described at: https://learn.microsoft.com/en-us/windows/wsl/connect-usb
+
+```sh
+# You can list devices using: 
+
+(Powershell)$ ./wslusb.ps1 -List
+
+# Get the BUSID of the device you want to mount
+
+(Powershell)$ ./wslusb.ps1 -Attach <busid>
+
+# Check that the device is correctly mounted into WSL2
+
+(WSL2)$ lsusb # you should see your device here
+
+# Detach the device with
+
+(Powershell)$ ./wslusb.ps1 -Detach <busid>
+```
+
+### 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.
+
+Power users might prefer to work in sources tree in a native GNU/Linux
+environment as explained above.
+
+### More
+
+Refer to [./doc](doc) for more (using MQTT, WebApp etc).
+
 
 ## 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
@@ -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:

scripts/wslusb.ps1

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: ZLib
+# This script can be used to attach and detach a device to your WSL2 distribution
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory= $false, HelpMessage = "Busid of the device you want to bind")]
+    [Alias("b")]
+    [string]$Busid,
+
+    [Switch]$Attach,
+    [Switch]$Detach,
+    [Switch]$List
+)
+
+# Unblock the script file
+Unblock-File -Path $MyInvocation.MyCommand.Path
+
+Function List-devices {
+    usbipd list
+}
+
+Function Attach-device {
+    param(
+        [string]$Busid
+    )
+    Write-Host "Attaching device $Busid"
+    usbipd bind --busid $Busid --force
+    usbipd attach --wsl --busid $Busid --auto-attach
+}
+
+Function Detach-device {
+    param(
+        [string]$Busid
+    )
+    Write-Host "Detaching device $Busid"
+    usbipd detach --busid $Busid
+    usbipd unbind --busid $Busid
+}
+
+if ($Attach -or $Detach -or $List)
+{
+    if($List)
+    {
+        List-devices
+    }
+    if ($Detach)
+    {
+        if ($Busid)
+        {
+            Detach-device -Busid $Busid
+        }
+        else
+        {
+            Write-Host "Busid not specified"
+        }
+    }
+    if ($Attach)
+    {
+        if ($Busid)
+        {
+            Attach-device -Busid $Busid
+        }
+        else
+        {
+            Write-Host "Busid not specified"
+        }
+    }
+}
+else
+{
+    Write-Host "No argument specified. Use -Attach, -Detach or -List"
+    Write-Host 'Ex: ./wslusb.ps1 -b "5-3" -Attach'
+}