Skip to content

Commit 7e49fca

Browse files
rzrrzr
committed
SWPROT-8953: Docs add Quickstart instructions (SiliconLabsSoftware#72)
Origin: SiliconLabsSoftware#41 Signed-off-by: Philippe Coval <philippe.coval@silabs.com>
1 parent 71e1a37 commit 7e49fca

File tree

1 file changed

+130
-2
lines changed

1 file changed

+130
-2
lines changed

‎README.md

+130-2
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,9 @@
22

33
## About
44

5-
Z-Wave-Protocol-Controller is a Linux application to control Z-Wave networks with a Silicon Labs NCP,
6-
It has grown as part of Unify SDK project and is now maintained as an external project.
5+
Z-Wave-Protocol-Controller is a Linux application to control Z-Wave
6+
networks with a Silicon Labs NCP, It has grown as part of Unify SDK
7+
project and is now maintained as an external project.
78

89
## News
910

@@ -22,6 +23,133 @@ Or relevant sources pages, to get started head to:
2223

2324
## Quickstart
2425

26+
### Native (Linux) build
27+
28+
The project is CMake based, to prepare the environment,
29+
have a look at [./helper.mk](helper.mk)'s details
30+
for needed steps to setup developer system before using CMake normally.
31+
32+
At the moment stable version of Debian (12) is supported,
33+
so it should work also in relatives projects (Ubuntu, RaspiOS, WSL2 etc)
34+
and should be easy to adapt to other distributions.
35+
36+
```sh
37+
sudo apt-get install -y sudo make git
38+
39+
git clone https://github.com/SiliconLabsSoftware/z-wave-protocol-controller
40+
cd z-wave-protocol-controller
41+
42+
./helper.mk help
43+
./helper.mk setup # To setup developer system (once)
44+
./helper.mk VERBOSE=1 # Default build tasks verbosely (depends on setup)"
45+
./helper.mk run # Run entry-point application
46+
```
47+
48+
It should print zpc's help.
49+
50+
To use it, a Silicon Labs' Z-Wave NCP should be plugged in USB port.
51+
52+
To setup the device zwave_ncp_serial_api_controller application should be flashed using
53+
[simplicity-studio](https://www.silabs.com/developer-tools/simplicity-studio)
54+
55+
Alternatively demo-applications package can be downloaded from
56+
[SiliconLabs SDK repository](https://github.com/SiliconLabs/simplicity_sdk/releases)
57+
and flashed using command-line tool
58+
[SimplicityCommander](https://www.silabs.com/documents/public/software/SimplicityCommander-Linux.zip)
59+
.
60+
61+
Then to verify you can check firmware version using zpc:
62+
63+
```sh
64+
lsusb # Should list the NCP device (WSL users should attach device first)
65+
serial=$(ls /dev/serial/by-id/usb-Silicon_Labs* | head -n1)
66+
./helper.mk all run run_args="--zpc.serial=${serial} --zpc.ncp_version"
67+
# <i> [zpc_ncp_update] chip_serial_api_version: 7.23.1
68+
```
69+
70+
Then let's interact with ZPC's inbuilt shell without installing it.
71+
72+
```sh
73+
sudo apt install -y mosquitto # Is a strong runtime dependency
74+
serial=$(ls /dev/serial/by-id/usb-Silicon_Labs* | head -n1)
75+
run_args="--zpc.serial=${serial}"
76+
mapdir="applications/zpc/components/dotdot_mapper/rules"
77+
run_args="$run_args --mapdir=${mapdir}"
78+
datastore_file="tmp.db"
79+
run_args="$run_args --zpc.datastore_file=${datastore_file}"
80+
cache_path="tmp"
81+
run_args="$run_args --zpc.ota.cache_path=${cache_path}"
82+
mkdir -p ${cache_path}
83+
./helper.mk run run_args="$run_args"
84+
85+
86+
ZPC>help
87+
==================================================
88+
Unify Command line interface Help:
89+
==================================================
90+
(...)
91+
exit :Exit the application
92+
(...)
93+
zwave_home_id Print Z-Wave Home ID
94+
(...)
95+
zwave_add_node :Add a Z-Wave node to the network
96+
(...)
97+
zwave_set_default Reset Z-Wave network
98+
(...)
99+
ZPC> zwave_home_id
100+
Z-Wave Home ID:
101+
1BADC0DE
102+
ZPC> zwave_add_node
103+
(...)
104+
```
105+
106+
Set endnode to learn mode and the controller should see it:
107+
108+
```sh
109+
(...)
110+
Please verify the DSK and insert the missing part (first 5 digits)
111+
Usage: zwave_accept_dsk <insert the first two byte of the DSK in [decimal]>
112+
ZPC> zwave_accept_dsk (...)
113+
```
114+
115+
Then you will have to learn how to use couple of shell commands
116+
"attribute_store_log" and "attribute_store_set_desired",
117+
as explained in the reference documentation.
118+
119+
```sh
120+
ZPC>attribute_store_log
121+
(...)
122+
ZPC>attribute_store_log_search OnOff
123+
(...)
124+
│ │ │ │───(110) ZCL OnOff OnOff ..................................... 0
125+
(...)
126+
ZPC>attribute_store_set_desired 110,1
127+
(...)
128+
```
129+
130+
### More
131+
132+
Refer to [./doc](doc) for more (using shell, MQTT, WebApp etc).
133+
134+
135+
### Docker build
136+
137+
The fastest (less than 20min) way to build z-wave-protocol-controller from scratch
138+
is to delegate all tasks to docker.
139+
140+
```sh
141+
docker build https://github.com/SiliconLabsSoftware/z-wave-protocol-controller.git#ver_1.7.0
142+
```
143+
144+
This one-liner will do download latest release, setup environment, build, test, package...
145+
146+
Also a docker-compose file is provided to start ZPC and use it along a MQTT client
147+
(eg:
148+
[mosquitto-clients](https://github.com/eclipse-mosquitto/mosquitto/)
149+
).
150+
151+
Power users might prefer to work in sources tree in a native GNU/Linux
152+
environment as explained above.
25153

26154
## Contributing
27155

0 commit comments

Comments
 (0)