Improved CONTRIBUTING.md file

* Fixed one issue with example
* Added instruction how to start mosquitto server
* Replaced test.mosquito.org with localhost, because it is
  really easy to run mosquitto server
* Wrapped too long lines
* Added some notes

CONTRIBUTING.md

@@ -2,8 +2,15 @@
 
 ## MQTT broker
 
-An optional MQTT broker, should you wish to publish messages  locally.
-`mosquitto` is extremely easy to set up.
+An MQTT broker, should you wish to publish messages locally.
+`mosquitto` is extremely easy to set up. When you do not do any configuration,
+and you start the service like this:
+
+```bash
+systemctl start mosquitto
+```
+
+The broker will listen on port 1883 for unencrypted connections.
 
 ## HTTP server
 
@@ -27,12 +34,12 @@ programs.
 
 ### Terminal 1
 
-Start `yggd` on the user's session bus, connecting it to the broker
-`test.mosquitto.org` over an unencrypted TCP connection, log judiciously to
+Start `yggd` on the user's session bus, connecting it to the MQTT broker
+`localhost` over an unencrypted TCP connection, log judiciously to
 `stdout`.
 
 ```
-go run ./cmd/yggd --server tcp://test.mosquitto.org:8883 --log-level trace --client-id $(hostname)
+go run ./cmd/yggd --server tcp://localhost:1883 --log-level trace --client-id $(hostname)
 ```
 
 ### Terminal 2
@@ -49,32 +56,46 @@ Subscribe to all the MQTT topics the `yggd` client will publish and subscribe to
 to monitor the MQTT traffic.
 
 ```
-sub -broker tcp://test.mosquitto.org:8883 -topic yggdrasil/$(hostname)/#
+sub -broker tcp://localhost:1883 -topic yggdrasil/$(hostname)/#
 ```
 
 ### Terminal 4
 
 Publish a "PING" command to the `yggd` "control/in" topic.
 
 ```
-go run ./cmd/yggctl generate control-message --type command '{"command":"ping"}' | pub -broker tcp://test.mosquitto.org:8883 -topic yggdrasil/$(hostname)/control/in
+go run ./cmd/yggctl generate control-message --type command '{"command":"ping"}' | \
+    pub -broker tcp://localhost:1883 -topic yggdrasil/$(hostname)/control/in
 ```
 
 You should see the message logged to the output of `sub` in [Terminal
 3](#terminal-3) and receipt of the message logged in the output of `yggd` in
-[Terminal 1](#terminal-1).
+[Terminal 1](#terminal-1). The `echo` worker does not receive any message in this
+case.
 
-Now publish a data message to the echo worker.
+Now publish a data message "hello" to the `echo` worker.
 
 ```
-go run ./cmd/yggctl generate data-message --directive worker "hello" | pub -broker tcp://test.mosquitto.org:8883 -topic yggdrasil/$(hostname)/data/in
+go run ./cmd/yggctl generate data-message --directive echo "hello" | \
+    pub -broker tcp://localhost:1883 -topic yggdrasil/$(hostname)/data/in
 ```
 
+> Note: if you implemented your own worker (e.g. called cool_worker),
+> you will need to replace the `echo` directive with the name of your
+> worker (--directive cool_worker).
+
 Again, you should see the message logged by the `sub` command in [Terminal
 3](#terminal-3), the receipt of the message logged in the output of `yggd` in
 [Terminal 1](#terminal-1). This time, you should see output in [Terminal
 2](#terminal-2) when the echo worker receives the message.
 
+There is another option how to test the echo worker. You can use the `yggctl`
+like this:
+
+```bash
+echo -n "hello" | go run ./cmd/yggctl dispatch -w "echo" -
+```
+
 ## Running `yggd` on the system bus
 
 This quickstart assumes yggdrasil will communicate with workers over the user's
@@ -90,7 +111,7 @@ Then start `yggd`, ensuring the environment variable `DBUS_SESSION_BUS_ADDRESS`
 is undefined.
 
 ```
-sudo go run ./cmd/yggd --server tcp://test.mosquitto.org:8883 --log-level trace --client-id $(hostname)
+sudo go run ./cmd/yggd --server tcp://localhost:1883 --log-level trace --client-id $(hostname)
 ```
 
 # Running `yggd`
@@ -127,7 +148,8 @@ sudo firewall-cmd --zone public --add-port 2345/tcp --permanent
 Start `dlv` using the `debug` command:
 
 ```
-sudo /root/go/bin/dlv debug --api-version 2 --headless --listen 0.0.0.0:2345 ./cmd/yggd -- --config ./data/yggdrasil/config.toml
+sudo /root/go/bin/dlv debug --api-version 2 --headless --listen 0.0.0.0:2345 \
+    ./cmd/yggd -- --config ./data/yggdrasil/config.toml
 ```
 
 Next, from your host, connect to the dlv server, using either `dlv attach` or by
@@ -202,7 +224,8 @@ message to the broker, destined for one of the topics `yggd` is subscribed to.
 To watch a topic for messages, subscribe to it with `sub`:
 
 ```
-sub -broker tcp://test.mosquitto.org:8883 -topic yggdrasil/$CLIENT_ID/data/in -topic yggdrasil/$CLIENT_ID/data/out -topic yggdrasil/$CLIENT_ID/control/out
+sub -broker tcp://localhost:1883 -topic yggdrasil/$CLIENT_ID/data/in \
+    -topic yggdrasil/$CLIENT_ID/data/out -topic yggdrasil/$CLIENT_ID/control/out
 ```
 
 ## Publish a message
@@ -211,7 +234,8 @@ A client can be sent a `PING` command by generated a control message and
 publishing it to the client's "control/in" topic:
 
 ```
-yggctl generate control-message --type command '{"command":"ping"}' | pub -broker tcp://test.mosquitto.org:8883 -topic yggdrasil/$CLIENT_ID/control/in
+yggctl generate control-message --type command '{"command":"ping"}' | \
+    pub -broker tcp://localhost:1883 -topic yggdrasil/$CLIENT_ID/control/in
 ```
 
 Activity should occur on the terminal attached to `yggd`, and a `PONG` event
@@ -222,7 +246,8 @@ Similarly, a data message can be published to a client using `yggctl generate`
 and `pub`.
 
 ```
-yggctl generate data-message --directive echo hello | pub -broker tcp://test.mosquitto.org:8883 -topic yggdrasil/$CLIENT_ID/data/in
+yggctl generate data-message --directive echo hello | \
+    pub -broker tcp://localhost:1883 -topic yggdrasil/$CLIENT_ID/data/in
 ```
 
 # Code Guidelines