Repository navigation
Software Configuration
Configre the SCCS by editing config/sccs.conf. edit with a text editor such as nano (sudo nano config/sccs.conf) or access it through it's share (\\10.10.10.1\sccs\config\sccs.conf).Restart the service for changes to take effect:
sudo systemctl restart sccsconfig/sccs.conf.dist is the template the installer copies on first install or if the config file does not exist. When you pull an update that adds new keys, diff your live config against it and merge by hand; the installer never overwrites sccs.conf.
[system] relates to the Flask webserver: host (0.0.0.0 means the SCCS will listen on all network interfaces), port (5000 — nginx proxies port 80 to it), and debug (for development only). secret_key is generated automatically by the installer on first install.
[logging] sets the log level (INFO by default), where logs go (logs/, one file per day), and how long they're kept (log_retention_days, 31 by default). clock_sync_timeout_s is worth knowing about: after a power cut the Raspberry Pi's clock can be wrong until NTP syncs, so SCCS waits up to this many seconds at boot before picking Day/Evening/Night and running startup lighting. Set it to 0 to skip the wait.
[system] development_mode enables diagnostic tools on the Settings tab for simulating hardware conditions during SCCS development (force phase, GPS no-fix/no-hardware, force reed, toast test panel). Leave false for normal use.
There are three lighting phases: Day, Evening, and Night. Phase changes are the primary driver of automatic lighting.
On a phase change, the following elements ramp to their new levels as set in the configuration file:
- Reed-linked lights
- Ambient lights
- Touchscreens
- UI theme
- Scenes that say “day/evening/night levels”
If a light has no entry for the current phase in [reed_phases.*] / [ambient.*]then that light level does not change.
When the clock crosses a boundary (or you Save new timing that moves “now” into a different phase):
- Active scene is cleared — phase automation takes over again.
- Manual slider overrides are cleared — levels return to reed/ambient rules for the new phase. Relays are the exception (they keep their last manual on/off).
-
Lights that are allowed to run (reed open for reed-linked; any reed open for ambient, depending on config) ramp to the new phase’s brightness over
[lighting] phase_ramp_time_ms— not an instant snap. - Ambient is re-evaluated if the campsite is still “occupied” (at least one reed open).
- Screens move to the new phase’s brightness percentage.
- UI colour mode follows Day → light / Evening·Night → dark, unless you locked colour mode by hand (manual mode clears when the phase’s natural mode would disagree later).
So when you set Day levels high and Night levels low, you are defining what people see when doors open and what happens automatically as the evening progresses with a door still open.
-
Day — usually bright white for work areas when a panel is open in daylight; ambient often
0so exterior doesn’t run in full sun. - Evening — dimmer “arrive at camp / cook” levels; often when exterior ambient first comes on.
-
Night — lowest practical levels (and red on
rgb_buglights if you want less bug attraction). Rooftop tent still respects the closed-reed safety lockout.
Reed closed → that reed’s linked light stays off regardless of phase. Phase only decides the target when the reed opens (and when phase changes while it stays open).
Sunrise and sunset come from the GPS fix, or from the fallback coordinates/timezone in [gps] when there is no fix.
| Phase | How its start is chosen | Config key |
|---|---|---|
| Day | Sunrise plus an offset in minutes | [phases] day_offset_minutes |
| Evening | Sunset minus an offset in minutes | [phases] evening_offset_minutes |
| Night | A fixed clock time (half-hour steps from 7:30 PM to midnight) |
[phases] night_start_minutes (legacy: night_start_hour) |
Example: with day_offset_minutes = 45 and sunrise at 7:06 AM, Day starts at 7:51 AM. With evening_offset_minutes = 45 and sunset at 5:38 PM, Evening starts at 4:53 PM.
After a power cut the Raspberry Pi’s clock may be wrong until NTP syncs. [logging] clock_sync_timeout_s (and the GPS startup/loss timeouts under [phases]) control how long SCCS waits before trusting time and sun data — if the clock is wrong, phases will be wrong.
You do not need to edit sccs.conf by hand for day-to-day timing tweaks. On the Settings → Phases tile, under Adjust phase start times:
- Change Day / Evening offsets with the ± buttons or the number field (minutes)
- Pick Night start from the dropdown (7:30 PM … Midnight, every 30 minutes)
-
Save writes the values to
config/sccs.conf, recalculates today’s schedule, and updates the phase timeline immediately (no service restart). If “now” falls in a different phase after Save, the same change behaviour as above runs (ramps, clear overrides/scenes, etc.). - Cancel restores the fields to the last saved values
The three phase cards above the editor show the resolved wall-clock times for today (after applying sunrise/sunset and the night rule below).
Night is a fixed clock time; Evening tracks sunset. In short winter days, sunset − offset can be after your chosen Night clock time (or Night would cut Evening short).
SCCS always uses:
effective Night start = the later of (Evening start, Night clock time)
So if you set Night to 7:30 PM but Evening only begins at 8:10 PM, Night actually starts at 8:10 PM — Evening is never skipped or run “backwards.” If Evening starts at 4:53 PM and Night is 8:00 PM, Night starts at 8:00 PM as usual.
After you Save, the Night card and timeline show that effective time. When planning Night levels, remember: a late sunset can delay Night until Evening has finished starting.
Each reed switch is a door or panel sensor: closed turns its linked lights and screens off, open ramps them to whatever brightness the current phase defines.
A reed can control one or more lights (the controls: field in [reeds], or it defaults to a light with the same internal name). When a reed changes state, any manual override or active scene on its linked lights clears, and ambient lights re-evaluate in case this changed the overall "any door open" state (see below).
One reed can depend on another via [reeds.interlocks] — e.g. a secondary door only counts as open if the main door is too. Reed reads are debounced twice over ([reed_monitor]): a run of consecutive matching GPIO polls before a transition is accepted, plus a minimum gap between accepted transitions, to filter noise on long cable runs. Between the software debounce and hardware filtering, the defaults rarely need changing.
When a reed is open, its linked light ramps to whatever the current phase defines for it:
[reed_phases.example_light]
day = 100
evening = 15
night = 3,redA level of 0 forces the light off; an omitted phase key leaves the light alone (config load logs a warning as a reminder, but it doesn't change the light or fail startup). If the phase changes while the door is still open, the light re-ramps to the new phase's level — or stays put if that phase has no level defined. Colour (red, white) only applies to rgb_bug lights.
Ambient lights are lights that turn on to illuminate your campsite and remain turned on for as long as at least one reed switch is opened. Default accent lights are accent lights (lights installed underneath the camper that point down to create a gentl glow) and awning lights. Ambient lights fade on when any reed is open and the relevant phase begins, and only follow scenes while at least one reed is open. Normally when all reed switches are closed, the ambient lights will fade out and not turn on with the next evening phase. This can be changed by setting all_closed_action to dim in the config, then they will fade to their night levels when all reeds are closed. Useful for keeping a small level of lighting on overnight if people get up to use the bathroom.
Ambient levels are re-applied when occupancy changes (the first door opens or the last one closes) or the phase changes while still occupied — opening more doors while already occupied so that the lights don't keep getting retriggered. A manual slider/toggle change sticks for the rest of the current phase and clears on the next phase change or scene activation.
One-shot lighting presets — "Bedtime", "All Off" — each in their own [scenes.name] section with name, icon, order, description, and per-light levels. A light entry can be a fixed value, a colour (kitchen_panel = 60,white), or a phase reference (accent = night) that pulls from [reed_phases.*] or falls back to [ambient.*]. Four special scene names apply everywhere — all_off, day_levels, evening_levels, night_levels — and combine with per-light overrides, so you can set most lights to a phase level and just a couple to something else.
Activating a scene clears existing overrides, applies scene levels at the scene ramp time, and shows a confirmation toast. Reed-linked lights in the scene only ramp if their reed is open. The scene stays active until a reed changes state, the phase changes, a slider moves, or another scene activates — then normal reed/phase behaviour resumes.
Moving a slider or toggle creates a manual override that overrides automation and scenes until the linked reed changes state or the phase changes. Relays ([gpio]) are the exception — they hold their last manual setting indefinitely or until system restart since these are typically for lighting circuits or water pumps.
Ramp times for UI/reed/scene/phase changes live under [lighting] in the config file.
If the rooftop tent reed is closed, its light is forced to 0% regardless of scene or slider input, since the LED strip may be pressed against bedding. The UI disables the control while closed; scenes targeting the tent still run for other lights. Normal reed + phase behaviour resumes once the tent reed opens.
Touchscreens can follow a linked reed over SSH — closed turns off the touchscreen display to save power, open sets it to the day/evening/night percentage configured for that screen if the backlight is dimmable otherwise it turns the screen on/off. Each row is:
internal_name = Friendly Name | linked_reed | host | username | brightness_path | icon | day | evening | night | blank_path | mac
If touchscreens are connected and online during setup these can be configured during the setup process. Installer menu option 8 (Touchscreens) let you search and add touchscreens and the script will probe the device for it's brightness path, setup the touchscreen to respond to SSH commands and set the app to autostart when the touchscreen boots so use that first for quick setup.
The interface follows the phase by default — light in Day, dark in Evening/Night — but can be switched manually; the manual choice sticks until the phase later requires the opposite mode. Several CSS themes ship in the UI and the active one is picked in the UI and stored in config/active_theme.json so the theme stays active until manually changed.
An GPS onboard the SCCS core provides position and time data. If there's no fix (including at startup), fallback coordinates and timezone from [gps] are used for sun times and weather instead. Suburb lookups use online reverse geocoding through the Nominatim service and fall back to an offline list of nearby towns.
Ambient, fridge, and freezer temperatures come from DS18B20 sensors on the 1-Wire bus on the SCCS core. Use menu option # in the installer to scan and detect temp sensors. The current temps for each sensor will be displayed to assist in determening which sensor is which. Outside defaults to the first device found if left blank; fridge and freezer are optional. Fridge/freezer temps will only appear on the UI if they are defined in the config.
If there is no ambient temp sensor detected then the current temperature on the UI will be scraped from Open-Meteo or wttr.in using the GPS coordinates. Humidity, overnight temp, forecast and any weather warnings are scraped from the same sources. Data is cached for about five minutes. If every live source fails then the last known data is served.
Water tank level comes from a resistive fuel-sender. Configure the min/max resistance levels of your sensor (check the sensor data sheet) and set the values [sensors] (water_resistance_empty / _full) to a 0–100% figure. The config is set for 33/240ohm, same as typical fuel sensors. Water percentage is based from tank literage input into the config by you - only the level is actually measured, not volume. A failed read just holds the last good percentage.
Battery and solar data come from a Victron SmartShunt and/or SmartSolar MPPT over Bluetooth Instant Readout. VE.Direct cables probably work but haven't been tested for this project. Full pairing steps are on Victron Setup; this integration is monitoring-only, SCCS doesn't control charge profiles or loads. A device goes stale in the UI if no advertisement arrives within [victron] stale_timeout.
Configured under [sonos]:
-
interface_addr— the Raspberry Pi's IP on the Sonos LAN/Wi-Fi so discovery does not scan the WAN interface instead -
player_name— preferred speaker (partial, case-insensitive match). Can also be set in the UI settings tab. -
auto_select_first— if the preferred speaker is missing, use the first discovered one
The Home tile shows transport, volume, and now-playing when at least one speaker is found. If none are found the tile is hidden unless you turn on Show tiles with disconnected hardware in the appearance setting tile (in settings, not the home tab). The System tab tile lists discovered speakers; "Set default" switches the active speaker and updates player_name in the config.
Optional Apple Home / Siri bridge. Off by default. Set [homekit] enabled = true, keep bind_address on the LAN/Wi-Fi IP (10.10.10.1), and restart. Pair from Settings → HomeKit (QR + setup code) with the phone on LAN/Wi-Fi.
Siri and the Home app use the same manual-override rules as the web sliders. Full pairing, accessory list, Home hub / remote access, and mDNS troubleshooting: HomeKit.
Optional Google Home / Gemini bridge. Off by default. Set [matter] enabled = true, keep bind_address on the LAN/Wi-Fi IP, and restart. The LAN/Wi-Fi interface must have IPv6 link-local (installer menu 6). Pair from Settings → Google Home. Runs beside HomeKit. Full steps: Google Home.
The System tab shows and manages the Raspberry Pi's Wi-Fi/USB Internet connection. This is separate from the LAN/Wi-Fi/NAT/Pi-hole setup described in Networking.
The System tab's Explain tool shows why each light or relay is at its current level — user override, closed reed, active scene, safety clamp — and flags when the hardware doesn't match the commanded state (checked in the background, with a grace period after ramps before it warns).
Extra simulate/force tools (phase, reed, GPS, toast test) only appear when [system] development_mode is enabled — see Core app settings.
Toasts are the coloured messages that pop up at the bottom of the SCCS web UI to notify you of something important happening.
They appear on every open screen (touchscreens, phones etc).
| Colour | Meaning | Examples |
|---|---|---|
| Green | Success | Scene activated, GPS fix acquired |
| Blue | Info | Day / evening / night phase changed |
| Amber | Warning | GPS fix lost, hardware drift |
| Red | Error | Failed action (e.g. Sonos) |
Tap a toast (or the X) to dismiss it early. Most clear themselves after a few seconds.
Defaults live in config/sccs.conf under [toasts] (how long each type stays on screen) and [gps] toast_cooldown (stops GPS lost/acquired messages from spamming). Restart SCCS after edits
| Section | Covers |
|---|---|
[system], [logging]
|
Server host/port, secret key, development_mode, log level & retention |
[lighting] |
Ramp times |
[esp32], [lights], [gpio]
|
ESP serial ports, light pin map, relays |
[reeds], [reeds.interlocks], [reed_monitor]
|
Door sensors, dependencies, debounce |
[ambient.*], [reed_phases.*], [scenes.*]
|
Automated brightness tables and presets |
[phases] |
Day/Evening offsets, night start time (also editable in Settings → Phases) |
[gps] |
Fallback coordinates, update intervals |
[esp32 analog], [sensors], [tanks]
|
Water level and 1-Wire temperature config |
[victron] |
BLE MAC + Instant Readout keys |
[homekit] |
Optional Home / Siri bridge (off by default). See HomeKit. |
[matter] |
Optional Google Home / Gemini Matter bridge (off by default). See Google Home. |
[sonos] |
Speaker selection and polling |
[toasts], [ui]
|
Notification timing, default theme |