Valve cluster: refactor to make unit-testable

examples/valve/controller/README.md

@@ -0,0 +1,73 @@
+# Running the drinks machine app and controller
+
+To run this example matter application, you need a version of the example app
+and a controller. The example app can be compiled with gn / ninja, the
+controller functions can be used through the chip-repl python shell
+
+## App
+
+### Compiling the app on linux
+
+From the root of the chip tree
+
+```
+cd examples/valve/linux
+gn gen out/debug
+ninja -C out/debug
+```
+
+### Running the app on linux
+
+From the root of the chip tree
+
+```
+./examples/valve/linux/out/debug/valve-app --KVS /tmp/valve_kvs.json
+```
+
+The KVS file is where the commissioning data is stored for the app, so be sure
+to start the app with the same kvs file if you do not want to re-commission it
+every time. All the standard linux app flags also work for this app. Use --help
+to see the available options.
+
+## Controller
+
+### Compiling the chip-repl
+
+To compile the chip-repl, from the root of the chip tree:
+
+```
+. scripts/activate.sh
+./scripts/build_python.sh -i out/pyenv
+source out/pyenv/activate
+out/pyenv/bin/chip-repl
+```
+
+The chip-repl is a shell that lets you directly call python functions. It
+instantiates a controller object that can be used to communicate with devices.
+The controller is called devCtrl. By default, its KVS is at
+/tmp/repl-storage.json, but this can be changed on the command line if desired.
+Use --help to see options.
+
+### Commissioning the valve app
+
+As long as the controller and the application KVSs are kept constant, the app
+should only need to be commissioned once.
+
+To commission the device use:
+
+```
+from chip import ChipDeviceCtrl
+await devCtrl.CommissionOnNetwork(nodeId=1, setupPinCode=20202021, filterType=ChipDeviceCtrl.DiscoveryFilterType.LONG_DISCRIMINATOR, filter=3840)
+```
+
+### Interacting with the valve app
+
+To create a drinks machine controller:
+
+```
+import examples.valve.controller as DrinksController
+dm = DrinksController.DrinkMachine(devCtrl, 1)
+```
+
+You can now call functions on the drinks machine controller. Tab completion will
+work within the repl, so you can see the available options.

examples/valve/controller/__init__.py

@@ -0,0 +1,146 @@
+import random
+
+from enum import StrEnum
+from chip import ChipDeviceCtrl
+from chip.clusters.Types import NullValue
+import chip.clusters as Clusters
+
+
+MYSTERY_DRINK = "mystery mirrorball"
+
+
+class Bottle(StrEnum):
+    kBourbon = "bourbon"
+    kGin = "gin"
+    kCampari = "campari"
+    kVermouth = "vermouth"
+    kSourMix = "sour mix"
+    kSimpleSyrup = "simple syrup",
+
+
+class Oz:
+    def __init__(self, oz: float):
+        self.oz = oz
+
+    def time(self):
+        # One oz == approx 12s.
+        return self.oz * 12
+
+    def __eq__(self, other):
+        return self.oz == other.oz
+
+    def __lt__(self, other):
+        return self.oz < other.oz
+
+
+class DrinkMachine:
+    def __init__(self, devCtrl: ChipDeviceCtrl, node_id: int):
+        self.dev_ctrl = devCtrl
+        self.node_id = node_id
+        # TODO: Should this actually be modelled as an aggregator with bridged nodes so I can have a NodeLabel?
+        # Right now I'm going to leave this as something on the app side because it's a demo, but it's weird that we don't have writeable labels unless you model it strangely. Spec issue?
+        self.bottles: dict[Bottle, int] = {Bottle.kBourbon: 1, Bottle.kGin: 2,
+                                           Bottle.kCampari: 3, Bottle.kVermouth: 4, Bottle.kSourMix: 5, Bottle.kSimpleSyrup: 6}
+        self.recipes: dict[str, dict[Bottle, Oz]] = {}
+        self.add_recipe("negroni", {Bottle.kGin: Oz(1.5), Bottle.kCampari: Oz(1.5), Bottle.kVermouth: Oz(1.5)})
+        self.add_recipe("boulevardier", {Bottle.kBourbon: Oz(1.5), Bottle.kCampari: Oz(1.5), Bottle.kVermouth: Oz(1.5)})
+        self.add_recipe("bourbon sour", {Bottle.kBourbon: Oz(2), Bottle.kSourMix: Oz(1), Bottle.kSimpleSyrup: Oz(1.5)})
+        self.add_recipe("martini", {Bottle.kGin: Oz(2), Bottle.kVermouth: Oz(0.25)})
+        self.add_recipe("gimlet", {Bottle.kGin: Oz(2.5), Bottle.kSourMix: Oz(0.5), Bottle.kSimpleSyrup: Oz(0.5)})
+        self.add_recipe("old fashioned", {Bottle.kBourbon: Oz(2), Bottle.kSimpleSyrup: Oz(0.125)})
+        self.add_recipe("shot of bourbon", {Bottle.kBourbon: Oz(1.5)})
+        self.add_recipe("shot of gin", {Bottle.kGin: Oz(1.5)})
+        self.add_recipe("gin sour", {Bottle.kGin: Oz(2), Bottle.kSourMix: Oz(1), Bottle.kSimpleSyrup: Oz(0.5)})
+        self.add_recipe("manhattan", {Bottle.kBourbon: Oz(2), Bottle.kVermouth: Oz(1)})
+        self.add_recipe("campari sour", {Bottle.kGin: Oz(1), Bottle.kCampari: Oz(1),
+                        Bottle.kSourMix: Oz(0.75), Bottle.kSimpleSyrup: Oz(0.5)})
+        self.add_recipe(MYSTERY_DRINK, {})
+
+    def set_bottle_names(self, bottles: dict[Bottle, int]) -> bool:
+        ''' Bottle is a dict of bottle name to endpoint and should contain all 6 endpoints at once'''
+        if len(bottles) != 6:
+            return False
+        self.bottles = bottles
+
+    def get_bottle_names(self):
+        return self.bottles
+
+    def get_recipes(self):
+        return self.recipes
+
+    def add_recipe(self, name: str, ingredients: dict[Bottle, Oz]):
+        # TODO: should store somewhere permanent - simplest is to write out to file. In the meanwhile, we have a few pre-populated
+        self.recipes[name] = ingredients
+
+    async def _dispense_mystery(self):
+        num_ingredients = random.randint(1, 3)
+        bottles = set()
+        choice = random.choice(list(Bottle))
+        bottles.add(choice)
+        while len(bottles) < num_ingredients:
+            # If this matches something in the bottle list already, it won't be added
+            choice = random.choice(list(Bottle))
+            bottles.add(choice)
+
+        # we're going to aim for a 2.5 Oz shot with min 0.5 shot sizes
+        goal = 2.5
+        print(f"Creating your mystery beverage:")
+        ingredients = {}
+        total = 0
+        for bottle in bottles:
+            remaining = num_ingredients - len(ingredients.keys())
+            if remaining == 1:
+                oz = goal-total
+            else:
+                max_oz = goal - total - 0.5*(remaining-1)
+                # multiply by 2 because randrange likes ints
+                oz = random.randrange(1, max_oz*2, 1)/2
+            total += oz
+            ingredients[bottle] = Oz(oz)
+            print(f"\t{oz} Oz of {bottle}")
+
+        largest = max(ingredients, key=ingredients.get)
+        mystery_prefix = ['', 'giant', 'potent', 'disco-tastic', 'shiny', 'Dr.']
+        mystery_suffix = ['blaster', 'concoction', 'blend', 'cocktail']
+        mystery_extra_suffix = ['', 'jr', 'of wonder', 'esq']
+        name = []
+        name.append(random.choice(mystery_prefix))
+        name.append(largest)
+        name.append(random.choice(mystery_suffix))
+        name.append(random.choice(mystery_extra_suffix))
+        print(f'The {" ".join(name).strip()}')
+        print('Please enjoy responsibly.')
+        await self._dispense_ingredients(ingredients)
+
+    async def dispense(self, recipe: str):
+        if recipe == MYSTERY_DRINK:
+            return await self._dispense_mystery()
+
+        # TODO: be a bit nicer on the comparison here. Strings as keys aren't great, but I want the flexibility to add non-standard recipes
+        if recipe not in self.recipes.keys():
+            print(f"Unable to find the specified recipe. Available Recipes: {self.recipes.keys()}")
+            return
+        required_bottles = set(self.recipes[recipe].keys())
+        if not required_bottles.issubset(set(self.bottles)):
+            print('Recipe requires an ingredient that is not loaded into the drink machine')
+            print(f'Recipe requires: {required_bottles}')
+            print(f'Available: {self.bottles}')
+            return
+
+        ingredients = self.recipes[recipe]
+        self._dispense_ingredients(ingredients)
+
+    async def _dispense_ingredients(self, ingredients: dict[Bottle, Oz]):
+        for bottle, amount in ingredients.items():
+            ep = self.bottles[bottle]
+            time = amount.time()
+            await self.dev_ctrl.SendCommand(nodeid=self.node_id, endpoint=ep,
+                                            payload=Clusters.ValveConfigurationAndControl.Commands.Open(openDuration=time))
+
+    async def prime(self, endpoint: int):
+        await self.dev_ctrl.SendCommand(nodeid=self.node_id, endpoint=endpoint,
+                                        payload=Clusters.ValveConfigurationAndControl.Commands.Open(openDuration=NullValue))
+
+    async def stop(self, endpoint: int):
+        await self.dev_ctrl.SendCommand(nodeid=self.node_id, endpoint=endpoint,
+                                        payload=Clusters.ValveConfigurationAndControl.Commands.Close())

examples/valve/linux/.gn

@@ -0,0 +1,25 @@
+# Copyright (c) 2020 Project CHIP Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import("//build_overrides/build.gni")
+
+# The location of the build configuration file.
+buildconfig = "${build_root}/config/BUILDCONFIG.gn"
+
+# CHIP uses angle bracket includes.
+check_system_includes = true
+
+default_args = {
+  import("//args.gni")
+}

examples/valve/linux/BUILD.gn

@@ -0,0 +1,55 @@
+# Copyright (c) 2023 Project CHIP Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import("//build_overrides/chip.gni")
+
+import("${chip_root}/build/chip/tools.gni")
+import("${chip_root}/src/app/common_flags.gni")
+
+assert(chip_build_tools)
+
+import("${chip_root}/examples/common/pigweed/pigweed_rpcs.gni")
+
+config("includes") {
+  include_dirs = [
+    ".",
+    "include",
+  ]
+}
+
+executable("valve-app") {
+  sources = [
+    "include/CHIPProjectAppConfig.h",
+    "main.cpp",
+  ]
+
+  deps = [
+    "${chip_root}/examples/platform/linux:app-main",
+    "${chip_root}/examples/valve/valve-common",
+    "${chip_root}/src/lib",
+  ]
+
+  cflags = [ "-Wconversion" ]
+
+  include_dirs = [ "include" ]
+  output_dir = root_out_dir
+}
+
+group("linux") {
+  deps = [ ":valve-app" ]
+}
+
+group("default") {
+  deps = [ ":linux" ]
+}

examples/valve/linux/args.gni

@@ -0,0 +1,25 @@
+# Copyright (c) 2023 Project CHIP Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import("//build_overrides/chip.gni")
+
+import("${chip_root}/config/standalone/args.gni")
+
+chip_device_project_config_include = "<CHIPProjectAppConfig.h>"
+chip_project_config_include = "<CHIPProjectAppConfig.h>"
+chip_system_project_config_include = "<SystemProjectConfig.h>"
+
+chip_project_config_include_dirs =
+    [ "${chip_root}/examples/air-purifier-app/linux/include" ]
+chip_project_config_include_dirs += [ "${chip_root}/config/standalone" ]

examples/valve/linux/build_overrides

@@ -0,0 +1 @@
+../../build_overrides

examples/valve/linux/include/CHIPProjectAppConfig.h

@@ -0,0 +1,38 @@
+/*
+ *
+ *    Copyright (c) 2023 Project CHIP Authors
+ *    All rights reserved.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+#pragma once
+
+// include the CHIPProjectConfig from config/standalone
+#include <CHIPProjectConfig.h>
+
+#define CHIP_DEVICE_CONFIG_ENABLE_COMMISSIONER_DISCOVERY 0
+
+#define CHIP_DEVICE_CONFIG_ENABLE_COMMISSIONER_DISCOVERY_CLIENT 0
+
+#define CHIP_DEVICE_CONFIG_ENABLE_EXTENDED_DISCOVERY 1
+
+#define CHIP_DEVICE_CONFIG_ENABLE_COMMISSIONABLE_DEVICE_TYPE 1
+
+#define CHIP_DEVICE_CONFIG_DEVICE_TYPE 0x0042 // Water valve
+
+#define CHIP_DEVICE_CONFIG_ENABLE_COMMISSIONABLE_DEVICE_NAME 1
+
+#define CHIP_DEVICE_ENABLE_PORT_PARAMS 1
+
+#define CHIP_DEVICE_CONFIG_DEVICE_NAME "DISCO Drinks"