Merge pull request #87 from PortableProgrammer/dev

Modular architecture with abstract targets and enhanced ICS support

Author: PortableProgrammer

.github/workflows/docker-image.yml

@@ -14,19 +14,19 @@ jobs:
     steps:
       -
         name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       -
         name: Prepare
         id: prepare
         run: |
           DOCKER_IMAGE=portableprogrammer/status-light
-          DOCKER_PLATFORMS=linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64
+          DOCKER_PLATFORMS=linux/amd64,linux/arm/v7,linux/arm64
           VERSION=edge
 
           if [[ $GITHUB_REF == refs/tags/* ]]; then
             VERSION=${GITHUB_REF#refs/tags/v}
           fi
-          
+
           TAGS="--tag ${DOCKER_IMAGE}:${VERSION}"
           if [[ $VERSION =~ ^[0-9]{1,3}\.[0-9]{1,3}(\.[0-9]{1,3})?$ ]]; then
             TAGS="$TAGS --tag ${DOCKER_IMAGE}:latest"
@@ -37,10 +37,13 @@ jobs:
           echo "buildx_args=--platform ${DOCKER_PLATFORMS} --build-arg VERSION=${VERSION} --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') --build-arg VCS_REF=${GITHUB_SHA::8} ${TAGS} --file ./Dockerfiles/Dockerfile ./" >> "$GITHUB_ENV"
       -
         name: Set up QEMU
-        uses: docker/setup-qemu-action@v2
+        uses: docker/setup-qemu-action@v3
       -
         name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
+        uses: docker/setup-buildx-action@v3
+        with:
+          # Enable Docker layer caching
+          buildkitd-flags: --debug
       -
         name: Docker Buildx (build)
         run: |

.gitignore

@@ -2,6 +2,7 @@ __pycache__
 *.pyc
 .vscode/
 .devcontainer/
+.claude/
 build/
 dist/
 status-light/__pycache__

CLAUDE.md

@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Status-Light monitors user status across collaboration platforms (Webex, Slack) and calendars (Office 365, Google Calendar) to display the "busiest" status on a Tuya RGB LED smart bulb. The application runs as a continuous polling loop inside a Docker container.
+
+## Running the Application
+
+**Local execution:**
+```bash
+python -u status-light/status-light.py
+```
+
+**Docker (preferred):**
+```bash
+docker run -e SOURCES=webex,office365 -e WEBEX_PERSONID=... portableprogrammer/status-light
+```
+
+**Build Docker image locally:**
+```bash
+docker build -f Dockerfiles/Dockerfile -t status-light .
+```
+
+There is no formal test suite, linter configuration, or build system. Development testing is done manually through Docker.
+
+## Architecture
+
+### Core Application Flow
+
+`status-light/status-light.py` is the entry point containing the `StatusLight` class which:
+1. Validates environment variables and initializes configured sources
+2. Runs a continuous polling loop (configurable via `SLEEP_SECONDS`)
+3. Queries each enabled source for current status
+4. Applies status precedence rules to determine the "busiest" status
+5. Updates the Tuya smart light color accordingly
+6. Handles graceful shutdown via signal handlers (SIGHUP, SIGINT, SIGQUIT, SIGTERM)
+
+### Status Sources
+
+**Collaboration sources** (`sources/collaboration/`):
+- `webex.py` - Webex Teams presence API
+- `slack.py` - Slack presence with custom status emoji/text parsing
+
+**Calendar sources** (`sources/calendar/`):
+- `office365.py` - Microsoft Graph API free/busy
+- `google.py` - Google Calendar API free/busy
+- `ics.py` - ICS/iCalendar file support (RFC 5545 compliant, uses `icalendar` + `recurring-ical-events` for proper timezone and recurring event handling)
+
+### Status Precedence
+
+Status determination follows a strict hierarchy:
+1. **Source priority:** Collaboration always wins over Calendar (except UNKNOWN/OFF)
+2. **Within collaboration:** Webex > Slack
+3. **Within calendar:** Office 365 > Google > ICS
+4. **Status priority:** Busy > Tentative/Scheduled > Available > Off
+
+### Key Utilities
+
+- `utility/enum.py` - Status enumerations (CollaborationStatus, CalendarStatus, Color)
+- `utility/env.py` - Environment variable parsing and validation
+- `utility/util.py` - Helper functions including `get_env_or_secret()` for Docker secrets
+- `utility/precedence.py` - Status precedence selection logic (selects winning status from multiple collaboration and calendar sources)
+
+### Output Targets
+
+All targets implement the `LightTarget` abstract interface defined in `targets/base.py`:
+
+- `targets/base.py` - Abstract base class defining the light target interface (`set_color()`, `turn_off()`)
+- `targets/tuya.py` - Tuya smart bulbs (locked to COLOR mode, handles retry logic and DPS format conversion)
+- `targets/virtual.py` - Virtual light for testing (logs status changes, no hardware required)
+
+## Configuration
+
+All configuration is via environment variables (no config files). Key categories:
+
+- **Sources:** `SOURCES` (comma-separated: webex, slack, office365, google, ics)
+- **Target:** `TARGET` (tuya or virtual; default: tuya)
+- **Authentication:** Platform-specific tokens/IDs (e.g., `WEBEX_PERSONID`, `SLACK_BOT_TOKEN`, `O365_APPID`, `ICS_URL`)
+- **Colors:** `AVAILABLE_COLOR`, `SCHEDULED_COLOR`, `BUSY_COLOR` (predefined names or 24-bit hex)
+- **Light:** `LIGHT_BRIGHTNESS` (0-100 percentage; default: 50; auto-detects legacy 0-255 format)
+- **Device:** `TUYA_DEVICE` (JSON with protocol, deviceid, ip, localkey; required only when TARGET=tuya)
+- **Behavior:** `SLEEP_SECONDS`, `CALENDAR_LOOKAHEAD`, `LOGLEVEL`, `ACTIVE_DAYS`, `ACTIVE_HOURS_*`
+
+Secrets support `*_FILE` variants for Docker secrets integration.
+
+## CI/CD
+
+GitHub Actions (`.github/workflows/docker-image.yml`) builds multi-platform Docker images:
+- Platforms: linux/amd64, linux/arm/v6, linux/arm/v7, linux/arm64
+- Triggers: PRs to main (build only), pushes with `v*` tags (build + push to Docker Hub)
+- Published to: `portableprogrammer/status-light`
+
+## Documentation Files
+
+Keep these files in sync with code changes:
+- `README.md` - User-facing documentation for environment variables, setup, and usage
+- `CLAUDE.md` - Developer guidance for Claude Code (this file)
+
+Update when:
+- New or modified environment variables
+- New dependencies in `requirements.txt`
+- Architecture changes (new sources, targets, utilities)
+- Configuration options

Dockerfiles/Dockerfile

@@ -7,10 +7,10 @@ WORKDIR /usr/src/status-light
 # Install dependencies
 COPY ./requirements.txt ./
 RUN apt-get update \
-    && apt-get install -y gcc \
+    && apt-get install -y gcc libffi-dev \
     && rm -rf /var/lib/apt/lists/* \
     && pip install -r requirements.txt \
-    && apt-get purge -y --auto-remove gcc
+    && apt-get purge -y --auto-remove gcc libffi-dev
 
 # Copy the project
 COPY ./status-light .

README.md

@@ -40,6 +40,7 @@ services:
     image: portableprogrammer/status-light:latest
     environment:
       - "SOURCES=Webex,Office365"
+      - "TARGET=tuya"
       - "AVAILABLE_COLOR=green"
       - "SCHEDULED_COLOR=orange"
       - "BUSY_COLOR=red"
@@ -48,14 +49,17 @@ services:
       - "BUSY_STATUS=call,donotdisturb,meeting,presenting,pending"
       - "OFF_STATUS=inactive,outofoffice,free,unknown"
       - 'TUYA_DEVICE={ "protocol": "3.3", "deviceid": "xxx", "ip": "yyy", "localkey": "zzz" }'
-      - "TUYA_BRIGHTNESS=128"
+      - "LIGHT_BRIGHTNESS=50"
       - "WEBEX_PERSONID=xxx"
       - "WEBEX_BOTID=xxx"
       - "O365_APPID=xxx"
       - "O365_APPSECRET=xxx"
       - "O365_TOKENSTORE=/data"
       - "GOOGLE_TOKENSTORE=/data"
       - "GOOGLE_CREDENTIALSTORE=/data"
+      - "ICS_URL=https://example.com/calendar.ics"
+      - "ICS_CACHESTORE=/data"
+      - "ICS_CACHELIFETIME=30"
       - "SLACK_USER_ID=xxx"
       - "SLACK_BOT_TOKEN=xxx"
       - "SLACK_CUSTOM_AVAILABLE_STATUS=''"
@@ -125,12 +129,25 @@ secrets:
   - `slack`
   - `office365`
   - `google`
+  - `ics`
 - Default value: `webex,office365`
 
 If specificed, requires at least one of the available options. This will control which services Status-Light uses to determine overall availability status.
 
 ---
 
+### `TARGET`
+
+- *Optional*
+- Available values:
+  - `tuya` - Physical Tuya smart bulb (requires `TUYA_DEVICE`)
+  - `virtual` - Virtual light that logs status changes (for testing)
+- Default value: `tuya`
+
+Specifies the output target for status display. Use `virtual` for testing without hardware.
+
+---
+
 ### **Statuses**
 
 - *Optional*
@@ -155,6 +172,10 @@ If specificed, requires at least one of the available options. This will control
   - Google
     - `free`
     - `busy`
+  - ICS
+    - `free`
+    - `tentative`
+    - `busy`
 
 #### `AVAILABLE_STATUS`
 
@@ -204,14 +225,17 @@ if webexStatus == const.Status.unknown or webexStatus in offStatus:
   # Fall through to Slack
   currentStatus = slackStatus
 
-if (currentStatus in availableStatus or currentStatus in offStatus) 
-  and (officeStatus not in offStatus or googleStatus not in offStatus):
+if (currentStatus in availableStatus or currentStatus in offStatus)
+  and (officeStatus not in offStatus or googleStatus not in offStatus
+       or icsStatus not in offStatus):
 
-  # Office 365 currently takes precedence over Google
+  # Office 365 currently takes precedence over Google, Google over ICS
   if (officeStatus != const.Status.unknown):
     currentStatus = officeStatus
-  else:
+  elif (googleStatus != const.Status.unknown):
     currentStatus = googleStatus
+  else:
+    currentStatus = icsStatus
 
 if currentStatus in availableStatus:
   # Get availableColor
@@ -304,11 +328,13 @@ In the example above, the Slack custom status would match (since it is a case-in
 
 ### **Tuya**
 
+**Note:** Tuya configuration is only required when [`TARGET`](#target) is set to `tuya` (the default). If using `TARGET=virtual`, you can skip this section.
+
 #### `TUYA_DEVICE`
 
-- *Required*
+- *Required if [`TARGET`](#target) is `tuya`*
 
-Status-Light requires a [Tuya](https://www.tuya.com/) device, which are white-boxed and sold under many brand names. For example, the Tuya light working in the current environment is an [Above Lights](http://alabovelights.com/) [Smart Bulb 9W, model AL1](http://alabovelights.com/pd.jsp?id=17).
+Status-Light supports [Tuya](https://www.tuya.com/) devices, which are white-boxed and sold under many brand names. For example, the Tuya light working in the current environment is an [Above Lights](http://alabovelights.com/) [Smart Bulb 9W, model AL1](http://alabovelights.com/pd.jsp?id=17).
 
 Status-Light uses the [tuyaface](https://github.com/TradeFace/tuyaface/) module for Tuya communication.
 
@@ -326,13 +352,19 @@ Example `TUYA_DEVICE` value:
 
 **Note:** Status-Light will accept an FQDN instead of IP, as long as the name can be resolved. Tuya devices will typically register themselves with the last 6 digits of the device ID, for example `ESP_xxxxxx.local`.
 
-#### `TUYA_BRIGHTNESS`
+#### `LIGHT_BRIGHTNESS`
 
 - *Optional*
-- Acceptable range: `32`-`255`
-- Default value: `128`
+- Acceptable range: `0`-`100` (percentage)
+- Default value: `50`
+
+Set the brightness of your RGB light as a percentage (0-100%). Status-Light defaults to 50% brightness.
 
-Set the brightness of your Tuya light. This is an 8-bit `integer` corresponding to a percentage from 0%-100% (though Tuya lights typically don't accept a brightness value below `32`). Status-Light defaults to 50% brightness, `128`.
+**Legacy Format Auto-Detection:** For backward compatibility, values above 100 (or in the range 32-100) are automatically detected as the legacy 0-255 format and converted to percentage. For example, `LIGHT_BRIGHTNESS=128` is auto-detected and converted to 50%. To avoid confusion, use percentage values (0-100) for new configurations.
+
+**Note:** The legacy format was specific to Tuya's device scale. The new percentage format works with all light targets and is more intuitive.
+
+**Backward Compatibility:** `TUYA_BRIGHTNESS` is still supported as an alias for `LIGHT_BRIGHTNESS` but is deprecated. Use `LIGHT_BRIGHTNESS` for new configurations.
 
 ---
 
@@ -452,6 +484,70 @@ Since Google has [deprecated](https://developers.googleblog.com/2022/02/making-o
 
 ---
 
+### **ICS**
+
+**Note:** See [`CALENDAR_LOOKAHEAD`](#calendar_lookahead) to configure lookahead timing for Calendar sources.
+
+Status-Light uses the [icalendar](https://github.com/collective/icalendar) and [recurring-ical-events](https://github.com/niccokunzmann/python-recurring-ical-events) libraries to parse ICS files. These libraries correctly handle recurring events and cross-timezone event matching (e.g., a Pacific time event will be correctly detected when running in Mountain time).
+
+Status-Light's ICS source implements **RFC 5545 compliant** status detection based on the `TRANSP` (transparency) and `STATUS` properties, **plus Microsoft CDO extensions** for enhanced Office 365/Outlook compatibility:
+
+**Standard RFC 5545 Properties:**
+
+| Event Properties | Status-Light Status |
+|-----------------|---------------------|
+| `TRANSP=TRANSPARENT` | `free` (event doesn't block time) |
+| `STATUS=CANCELLED` | `free` (event was cancelled) |
+| `STATUS=TENTATIVE` | `tentative` (maps to BUSY-TENTATIVE in RFC terms) |
+| `STATUS=CONFIRMED` or unset | `busy` (default blocking event) |
+
+**Microsoft CDO Extensions** (Office 365/Outlook ICS exports):
+
+When present, the `X-MICROSOFT-CDO-BUSYSTATUS` property takes precedence and provides more granular status information:
+
+| CDO BUSYSTATUS Property | Status-Light Status |
+|------------------------|---------------------|
+| `FREE` or `0` | `free` |
+| `TENTATIVE` or `1` | `tentative` |
+| `BUSY` or `2` | `busy` |
+| `OOF` or `3` | `outofoffice` (away/out of office) |
+| `WORKINGELSEWHERE` or `4` | `workingelsewhere` (remote work) |
+
+**Status Precedence:** When multiple events exist in the lookahead window, the "busiest" status wins: `busy` > `outofoffice` > `workingelsewhere` > `tentative` > `free`.
+
+#### `ICS_URL`
+
+- *Required if `ics` is present in [`SOURCES`](#sources)*
+
+The URL to an ICS (iCalendar) file. This can be any publicly accessible URL that returns a valid `.ics` file, such as:
+- A shared Google Calendar ICS link
+- An Office 365 published calendar
+- Any other iCalendar-compatible calendar export
+
+Status-Light will fetch this file periodically (controlled by `ICS_CACHELIFETIME`) and check for events within the [`CALENDAR_LOOKAHEAD`](#calendar_lookahead) window.
+
+**Docker Secrets:** This variable can instead be specified in a secrets file, using the `ICS_URL_FILE` variable.
+
+#### `ICS_CACHESTORE`
+
+- *Optional, only valid if `ics` is present in [`SOURCES`](#sources)*
+- Acceptable value: Any writable location on disk, e.g. `/path/to/cache/`
+- Default value: `~`
+
+Defines a writable location on disk where the cached ICS file is stored.
+
+**Note:** This path is directory only. Status-Light will persist a file named `status-light-ics-cache.ics` within the directory supplied.
+
+#### `ICS_CACHELIFETIME`
+
+- *Optional, only valid if `ics` is present in [`SOURCES`](#sources)*
+- Acceptable range: `5`-`60`
+- Default value: `30`
+
+Set the number of minutes the cached ICS file remains valid before being re-fetched from the URL. A lower value means more frequent updates but more network requests.
+
+---
+
 ### **Active Times**
 
 If you prefer to leave Status-Light running all the time (e.g. headless in a Docker container), you may wish to disable status polling during off hours.

requirements.txt

@@ -5,4 +5,6 @@ O365
 google-api-python-client
 google-auth-httplib2
 google-auth-oauthlib
-slack-sdk
+slack-sdk
+icalendar
+recurring-ical-events

status-light/sources/calendar/google.py

@@ -1,5 +1,5 @@
 """Status-Light
-(c) 2020-2023 Nick Warner
+(c) 2020-2026 Nick Warner
 https://github.com/portableprogrammer/Status-Light/
 
 Google Calendar Source