mqtt-gateway v0.4.0

Author: stfnmllr

README.md

@@ -57,54 +57,54 @@ Preconditions:
 
 ### Gateway
 
-Print help (parameters):
-
+A list of all gateway parameters can be printed via:
 ```
 ./gateway -h
-
-Usage of ./gateway:
-  -configDir string
-    	configuration directory
-  -host string
-    	MQTT host (default "localhost")
-  -password string
-    	password
-  -port string
-    	MQTT port (default "1883")
-  -topicRoot string
-    	topic root (default "pico-cs")
-  -username string
-    	user name
 ```
+Execute gateway with MQTT host listening at address 10.10.10.42 (default port 1883):
+```
+./gateway -host 10.10.10.42
+```
+Execute gateway reading configurations files stored in directory /pico-cs/config
 
-...todo
+```
+./gateway -configDir /pico-cs/config
+```
 
 ### Configuration files
-To configure the gateway's command station and loco parameters [YAML files](https://yaml.org/) are used. The entire configuration can be stored in one file or in multiple files. During the start of the gateway the configuration directory (parameter configDir) and it's subdirectories are scanned for valid configuration files with file extension '.yaml' or '.yml'. The directory tree scan is a depth-first search and within a directory the files are visited in a lexical order. If a configuration for an object is found more than once the last one wins.
+To configure the gateway's command station and loco parameters [YAML files](https://yaml.org/) are used. The entire configuration can be stored in one file or in multiple files. During the start of the gateway the configuration directory (parameter configDir) and it's subdirectories are scanned for valid configuration files with file extension '.yaml' or '.yml'. The directory tree scan is a depth-first search and within a directory the files are visited in a lexical order. If a configuration for a device is found more than once the last one wins.
 
-Each object needs to define a name. As the object name is part of the [MQTT topic](#mqtt-topics) it must fullfil the following conditions:
+Each device needs to define a name. As the device name is part of the [MQTT topic](#mqtt-topics) it must fullfil the following conditions:
 - consist of valid MQTT topic characters and
 - must not contain characters "/", "+" or "#"
 
-All conditions are checked by the gateway on start and in case of a violation the program prints the respective error message and stops execution.
+If a device is assigned to a command station the command station acts whether as a primary or secondary.
+A primary command stations 'owns' the device, meaning that the command station registers for all commands of the device.
+A secondary command station listens and registers the events 'send' by the device and executes the correspondig commands to keep the device settings in sync with the primary command station.
+A device can be assigned to 0..1 primary command stations and 0..* secondary command stations.
 
 ### Embedded configuration files
 Beside using a configuration directory the configuration files can be embedded in the gateway executable:
 - store them in as part of the source code directory at mqtt-gateway/cmd/gateway/config and
 - build the binary 
 
-This is the prefered method using a static or default configuration. During the gateway start the embedded configuration files are scanned before the 'external' configuration files (configDir parameter), so an external object configuration would overwrite an embedded one.
+This is the prefered method using a static or default configuration. During the gateway start the embedded configuration files are scanned before the 'external' configuration files (configDir parameter), so an external device configuration would overwrite an embedded one.
 
 ### [Configuration examples](https://github.com/pico-cs/mqtt-gateway/tree/main/cmd/gateway/config_examples/)
 
 ## MQTT topics
 In MQTT a topic is a string the MQTT broker uses to determine which messages should be send to each of the connected clients. The client uses a topic to publish a message and uses topics to subscribe to messages it would like to receive from the broker.
 A topic can consist of more than one level - the character used to separate levels is '/'. A client might use wildcards when subscribing to topics, where '+' is the wildcard character for a dedicated level and '#' is the multi level wildcard character which can only be used as the last level of a topic. For further details about MQTT topics please see the [MQTT specification](https://mqtt.org/mqtt-specification/).
 
-The topic schema used by the gateway:
+The topic schema used by the gateway is
+
+```
+"<topic root>/<device type>/<device name>/<property>[/<command>]"
+```
 
+with 
 ```
-"<topic root>/<object type>/<object name>/<property>[/<command>]"
+device type: cs | loco
 ```
 
 The message payload is whether a json encoded atomic field (aka string, number, boolean) or a json encoded object.

cmd/gateway/config.go

@@ -19,7 +19,6 @@ type configSet struct {
 	logger        *log.Logger
 	csConfigMap   map[string]*gateway.CSConfig
 	locoConfigMap map[string]*gateway.LocoConfig
-	csList        []*gateway.CS
 }
 
 func newConfigSet(logger *log.Logger) *configSet {
@@ -33,16 +32,6 @@ func newConfigSet(logger *log.Logger) *configSet {
 	}
 }
 
-func (c *configSet) close() error {
-	var lastErr error
-	for _, cs := range c.csList {
-		if err := cs.Close(); err != nil {
-			lastErr = err
-		}
-	}
-	return lastErr
-}
-
 func isCSConfig(m map[string]any) bool {
 	if _, ok := m["host"]; ok {
 		return true
@@ -130,37 +119,29 @@ func (c *configSet) load(fsys fs.FS, path string) error {
 }
 
 func (c *configSet) register(gw *gateway.Gateway) error {
-	locoMap := map[string]string{}
-
-	for csName, csConfig := range c.csConfigMap {
-		c.logger.Printf("register central station %s", csName)
-		cs, err := gateway.NewCS(csConfig, gw)
+	for _, csConfig := range c.csConfigMap {
+		cs, err := gw.AddCS(csConfig)
 		if err != nil {
 			return err
 		}
-		c.csList = append(c.csList, cs)
-
-		for locoName, locoConfig := range c.locoConfigMap {
-
-			csAssignedName, ok := locoMap[locoName]
 
-			controlsLoco, err := cs.AddLoco(locoConfig)
+		for _, locoConfig := range c.locoConfigMap {
+			loco, err := gw.AddLoco(locoConfig)
 			if err != nil {
 				return err
 			}
-
-			if controlsLoco && ok {
-				return fmt.Errorf("loco %s is controlled by more than one central station %s, %s", locoName, csName, csAssignedName)
+			if err := cs.AddLoco(loco); err != nil {
+				return err
 			}
+		}
+	}
 
-			locoMap[locoName] = csName
+	for _, cs := range gw.CSList() {
+		c.logger.Printf("added command station %s", cs.Name())
+	}
 
-			if controlsLoco {
-				c.logger.Printf("added loco %s controlled by central station %s", locoConfig.Name, csConfig.Name)
-			} else {
-				c.logger.Printf("added loco %s to central station %s", locoConfig.Name, csConfig.Name)
-			}
-		}
+	for _, loco := range gw.LocoList() {
+		c.logger.Printf("added loco %s to central stations: primary %s secondaries %v", loco.Name(), loco.Primary(), loco.SecondaryList())
 	}
 	return nil
 }

cmd/gateway/config_examples/cs.yaml

@@ -1,7 +1,11 @@
 # configure central station
 name: cs01
 port: /dev/ttyACM0 # connected to serial port
-incls:
-  - .* # include all locos (regular expression)
-excls:
-  - br18 # exclude br18
+primary:
+  incls:
+    - .*   # primary command station for all devices (regular expression)...
+  excls:
+    - br18 # ...except br18
+secondary:
+  incls:
+    - .*   # secondary command station for all remaining devices

cmd/gateway/config_examples/loco.yml

@@ -1,8 +1,8 @@
 # configure loco
 name: br01
-addr: 1
+addr: 1 # decoder address
 fcts:
   light:
-    no: 0
+    no: 0 # function number for light
   horn:
-    no: 5
+    no: 5 # function number for horn

cmd/gateway/config_examples/multi.yaml

@@ -4,19 +4,23 @@
 name: cs02
 host: localhost # connected via WiFi TCP/IP connection
 port: 4242
-incls:
-  - br18
+primary:
+  incls:
+    - br18 # primary command station for br18
+secondary:
+  incls:
+    - .*   # secondary command station for all remaining devices
 ---
 # configure loco
 name: br18
-addr: 18
+addr: 18 # decoder address
 fcts:
   light:
-    no: 0
+    no: 0 # function number for light
   bell:
-    no: 5
+    no: 5 # function number for bell
   whistle:
-    no: 8
+    no: 8 # function number for whistle
 
 
 

cmd/gateway/config_test.go

@@ -11,31 +11,41 @@ import (
 func testLoad(t *testing.T) {
 	cmpCSConfigMap := map[string]*gateway.CSConfig{
 		"cs01": {
-			Name:  "cs01",
-			Port:  "/dev/ttyACM0",
-			Incls: []string{".*"},
-			Excls: []string{"br18"},
+			Name: "cs01",
+			Port: "/dev/ttyACM0",
+			Primary: gateway.Filter{
+				Incls: []string{".*"},
+				Excls: []string{"br18"},
+			},
+			Secondary: gateway.Filter{
+				Incls: []string{".*"},
+			},
 		},
 		"cs02": {
-			Name:  "cs02",
-			Host:  "localhost",
-			Port:  "4242",
-			Incls: []string{"br18"},
+			Name: "cs02",
+			Host: "localhost",
+			Port: "4242",
+			Primary: gateway.Filter{
+				Incls: []string{"br18"},
+			},
+			Secondary: gateway.Filter{
+				Incls: []string{".*"},
+			},
 		},
 	}
 	cmpLocoConfigMap := map[string]*gateway.LocoConfig{
 		"br01": {
 			Name: "br01",
 			Addr: 1,
-			Fcts: map[string]gateway.LocoFctConfig{
+			Fcts: map[string]gateway.LocoFct{
 				"light": {No: 0},
 				"horn":  {No: 5},
 			},
 		},
 		"br18": {
 			Name: "br18",
 			Addr: 18,
-			Fcts: map[string]gateway.LocoFctConfig{
+			Fcts: map[string]gateway.LocoFct{
 				"light":   {No: 0},
 				"bell":    {No: 5},
 				"whistle": {No: 8},

cmd/gateway/gateway.go

@@ -35,17 +35,16 @@ func lookupEnv(name, defVal string) string {
 
 func main() {
 
-	logger := log.New(os.Stderr, "gateway", log.LstdFlags)
+	logger := log.New(os.Stderr, "", log.LstdFlags)
 
-	config := &gateway.Config{}
+	config := &gateway.Config{Logger: logger}
 	configSet := newConfigSet(logger)
-	defer configSet.close()
 
-	flag.StringVar(&config.TopicRoot, "topicRoot", lookupEnv(envTopicRoot, gateway.DefaultTopicRoot), "topic root")
+	flag.StringVar(&config.TopicRoot, "topicRoot", lookupEnv(envTopicRoot, gateway.DefaultTopicRoot), "MQTT topic root")
 	flag.StringVar(&config.Host, "host", lookupEnv(envHost, gateway.DefaultHost), "MQTT host")
 	flag.StringVar(&config.Port, "port", lookupEnv(envPort, gateway.DefaultPort), "MQTT port")
-	flag.StringVar(&config.Username, "username", lookupEnv(envUsername, ""), "user name")
-	flag.StringVar(&config.Password, "password", lookupEnv(envPassword, ""), "password")
+	flag.StringVar(&config.Username, "username", lookupEnv(envUsername, ""), "MQTT username")
+	flag.StringVar(&config.Password, "password", lookupEnv(envPassword, ""), "MQTT password")
 
 	externConfigDir := flag.String("configDir", "", "configuration directory")