udmi

UDMI / Docs / Tools / BAMBI Backend Service

BAMBI: BOS Automated Management Building Interface

BAMBI is the backend service responsible for automating the management of Building Operating System (BOS) device and site models within the UDMI framework. It primarily listens for messages, typically from a Google Sheet, and then handles the import, export, and synchronization of site configuration data.

1. Prerequisites

Before running the service, ensure you have the Google Cloud SDK installed and configured on your local machine.

2. Running the BAMBI Service

2.1. Authentication

First, you’ll need to authenticate with your Google Cloud account. This command will open a browser window for you to log in.

gcloud auth login

Next, obtain application-default credentials. These credentials allow the BAMBI service to authenticate with Google Cloud APIs, such as Pub/Sub and Google Sheets, on your behalf.

gcloud auth application-default login \
--scopes="openid,[https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets](https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets)"

2.2. Starting the Service

To start the BAMBI service, navigate to your UDMI project’s root directory and run the bambi_service script with the required arguments.

Command syntax:

services/bin/bambi_service ${message_spec} ${cloning_dir} [options]

Arguments & Options:

Argument/Option	Description	Example
`${message_spec}`	(Required) Defines the message source. For a production environment, this will be a Google Cloud Pub/Sub topic. For local testing, you can use an MQTT broker.	`//pubsub/bos-platform-dev/udmis`, `//mqtt/localhost`
`${cloning_dir}`	(Required) An absolute path to a local directory where the service will temporarily clone git repositories for import and export operations.	`/tmp/udmi/sites`
`--local`	(Optional) A flag to run the service in a local-only mode, often used with an MQTT message_spec for development.	N/A
`--create`	(Optional) A flag that attempts to create the necessary Google Cloud Pub/Sub topics and subscriptions if they don’t already exist. This is useful for initial setup.	N/A
`local_origin_dir`	(Optional) Provides an absolute path to a local directory containing git repositories. This is used for testing to simulate a remote origin without making actual network requests.	`/home/user/udmi_test_repos`

2.3. Message Format

The BAMBI service expects incoming messages to be in a specific JSON format. The data field contains a base64 encoded JWT, while the attributes provide the context for the request.

{
  "data": "base64_encoded_identity_token",
  "attributes": {
    "project_id": "bos-platform-dev",
    "registry_id": "ZZ-TRI-FECTA",
    "request_type": "export",
    "source": "https://docs.google.com/spreadsheets/d/1a2b3c...",
    "user": "user@example.com",
    "import_branch": "main"
  }
}

data: An identity token (JWT) is required for authentication when using Pub/Sub but is optional for local MQTT testing. The token is used to verify that the request is from an expected Google Apps Script client.
attributes: A map of key-value pairs that define the requested operation. All attributes are required. request_type can be one of ["import", "export"]

3. Standalone Import/Merge

You can also run the import and merge functions as standalone scripts, which is useful for one-off tasks or debugging without starting the full service.

First, navigate to your UDMI root and source the common shell functions:

cd ${UDMI_ROOT}
source etc/shell_common.sh

Sync from Google Sheet to a local file (disk)

This command pulls the site model from the specified Google Sheet and saves it to a local file path.

# Usage: sync_bambi_site_model_to_disk <spreadsheet_id> <path_to_site_model>
sync_bambi_site_model_to_disk "1a2b3c..." "/home/user/site_models/site-A.json"

Sync from a local file (disk) to Google Sheet

This command takes a local site model file and pushes its contents to the specified Google Sheet where data templates are already populated.

# Usage: sync_disk_site_model_to_bambi <spreadsheet_id> <path_to_site_model>
sync_disk_site_model_to_bambi "1a2b3c..." "/home/user/site_models/site-A.json"

4. Building and Deploying the Container

To package the BAMBI service into a Docker container for deployment, use the provided container script.

First, set your target GCP project and optional UDMI namespace:

bin/set_project gcp_project[/udmi_namespace]

Then, navigate to the UDMI root and use the container script with one of the following commands:

# General Syntax: bin/container services.bambi {command} [repo]
bin/container services.bambi push

Command	Action
`prep`	Prepares dependencies and prerequisites for the container build.
`build`	Builds the Docker container image locally.
`push`	Pushes the built container image to a container registry (pushes to GHCR if `repo` is not specified).
`apply`	Applies the container to GKE cluster

This site is open source. Improve this page.