Merge pull request #7 from NREL/cleanup_document

Cleanup and improve documentation

.github/workflows/build.yml

@@ -43,6 +43,7 @@ jobs:
         uses: docker/build-push-action@v4
         with:
           context: .
+          target: base
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.output.labels }}

Dockerfile

@@ -1,4 +1,4 @@
-FROM ubuntu:20.04 as base
+FROM ubuntu:20.04 AS base
 
 WORKDIR /alfalfa-bacnet-bridge
 
@@ -16,6 +16,13 @@ RUN ln -sf /usr/bin/python3 /usr/bin/python \
     && poetry install --no-root --only main
 
 COPY alfalfa_bacnet_bridge alfalfa_bacnet_bridge
-COPY cli_setup.py .
 
-ENV TERM=xterm
+ENV TERM=xterm
+
+CMD poetry run python alfalfa_bacnet_bridge/alfalfa_watchdog.py alfalfa_bacnet_bridge/alfalfa_bacnet_bridge.py
+
+FROM base AS cli
+
+COPY cli/cli_setup.py .
+
+CMD poetry run python -i cli_setup.py

README.md

@@ -7,11 +7,37 @@ Alfalfa-BACnet-Bridge only requires [docker](https://www.docker.com/)
 
 ## Usage
 
-### Starting Device
+### Running the Bridge
+The following command will run the BACnet Alfalfa Bridge using the image from the github package.
+```bash
+# Pull latest image
+docker pull ghcr.io/nrel/alfalfa-bacnet-bridge:latest
+# Run Image
+docker run \
+    --detach \
+    -e ALFALFA_SITE=<alfalfa_site> \
+    -e ALFALFA_HOST=<alfalfa_host> \
+    -p 47808:47808/udp \
+    ghcr.io/nrel/alfalfa-bacnet-bridge:latest
+```
+
+### Environment Variables
+These are variables used to describe the bridge's connection to Alfalfa.
+| Variable | Description | Default |
+| --- | -------- | --- |
+| `ALFALFA_SITE` | The Alfalfa Site ID of the model of interest or an alias which points to a site of interest | MUST BE SET |
+| `ALFALFA_HOST` | The URL of the Alfalfa instance | MUST BE SET |
+
+When the specified `ALFALFA_SITE` is an alias the bridge will automatically switch sites when the alias is updated.
+
+## Development
+
+### Building and Starting Device
 1. Edit `.env` to reflect desired Alfalfa `host` and `site_id`
 1. Start device `./start_device.sh`
 
 ### Using CLI
+For development it is useful to be able to connect to your device from the same computer. 
 The CLI is a python REPL with precreates a [BAC0](https://bac0.readthedocs.io/en/latest/) `network` which the user can interact with.
 
 1. Start cli `./start_cli.sh`

alfalfa_bacnet_bridge/alfalfa_watchdog.py

@@ -66,9 +66,14 @@ async def main_loop(host: str, alfalfa_site: str, command: str):
                     child_process.kill()
                 elif child_process != None:
                     logger.info(f"Process '{child_process.pid}' died, restarting process")
-                child_process = Popen(["python", command, host, site_id])
+                child_process = Popen(["python", "-u", command, host, site_id])
                 logger.info(f"Spawned new child process: '{child_process.pid}'")
                 old_site_id = site_id
+
+        if site_id and is_process_alive(child_process) and client.status(site_id) != "running":
+            logger.info(f"Killing old child process: '{child_process.pid}'")
+            child_process.kill()
+
         elif site_id == None:
             logger.info(f"No site found with identifier: '{alfalfa_site}'")