watt42_viewlib/README.md

# Watt42 Viewlib

Watt42 Viewlib supports building browser-based front ends for Watt42 systems.
The purpose of those front ends is to visualize the state of a Watt42 system,
and to allow users to interact with it.

# Quickstart

## Create a View for a Watt42 System, using a Template

1. Ensure you've got Python and Poetry installed (see Prerequisites below).
2. Run the install script to create a new view project:

```bash
wget -q -O - https://source.c3.uber5.com/watt42-public/install/raw/branch/main/install.sh | TARGET=view bash
```

3. Follow the instructions printed by the install script to set up your new view
   project.


## "Hello World" Example

Given a Watt42 system that exposes the status of a smart device (`is_geyser_on`
is either `true` or `false`), the following code creates a simple view that
shows the status of the device.

```python
import os
import panel
from typing import Any

from watt42_viewlib import attach_w42_state

SYSTEM_ID = os.environ.get("WATT42_SYSTEM_ID", "invalid-system-id")
API_TOKEN = os.environ.get("WATT42_API_TOKEN", "invalid-api-token")

w42_state = panel.rx(None)

attach_w42_state(rx_var=w42_state, system_id=SYSTEM_ID, token=API_TOKEN)

def get_geyser_state(state: dict[str, Any]) -> bool:
    if not state:
        return False
    return state.get("is_geyser_on", False)

geyser_state = panel.rx(get_geyser_state)(w42_state)

indicator = panel.indicators.BooleanStatus(value=geyser_state, name="W42 Connected", color="success")

_ = indicator.servable()
```

# Prerequisites

You should be familiar with Python.

You need poetry installed:

- [Poetry](https://python-poetry.org/docs/#installing-with-the-official-installer)

# Demo

You can [run the sample online](https://viewlib-demo.watt42.com). The sample code is in [sample.py](./sample.py).

TODO: publish demo, provide more sophisticated demos online.

# Documentation

## Installation

Make sure you have poetry installed (see above), then run:

```bash
poetry install
```

You can now run the sample view in dev mode with:


```bash
poetry run panel serve sample.py --dev
```

Dev mode enables hot reloading, so any changes you make to the code will be
reflected immediately in the browser.

Your view will be available at `http://localhost:5006/sample`. In order for the
view to work, you need to configure an access token, and the Watt42 system that
you want to use. See #how-to-use below.

## How to use

Build your own front end for a Watt42 system by creating a Python script that
uses Viewlib. Start off with the sample code in [sample.py](./sample.py). You
can then extend the view by adding more widgets and logic.

1. Follow the installation instructions above.
2. Make sure you have a Watt42 system set up, and you have an access token for it. (TODO: link on how to do this)
3. Set the following environment variables:
    - `WATT42_SYSTEM_ID`: The ID of your Watt42 system.
    - `WATT42_API_TOKEN`: Your access token.


## Howtos

- See above on how to use Viewlib to build your own view.
- [How to add a diagram](https://source.c3.uber5.com/watt42-public/watt42_viewlib/src/branch/main/docs/howto_add_diagram.md)
- Learn more about how to build views with Panel:
  - [Panel Tutorials](https://panel.holoviz.org/tutorials/index.html)
  - [Panel Explanation](https://panel.holoviz.org/explanation/index.html)

## Reference

- [Watt42 Viewlib Documentation](https://source.c3.uber5.com/watt42-public/watt42_viewlib/src/branch/main/docs/reference.md)
- Visual components:
  - [Panel Component Gallery](https://panel.holoviz.org/reference/index.html)
  - [Panel App Gallery](https://panel.holoviz.org/gallery/index.html)
- [Panel API Reference](https://panel.holoviz.org/api/index.html)