Configuration Reference

Configuration Reference

Every setting ShellyElevate stores, what it controls, and the default. The keys here are the exact JSON keys you'd use with POST /settings over HTTP API, and they're also the same names used internally.

Settings are stored in an Android SharedPreferences file called ShellyElevateV2. Anything not listed here is internal bookkeeping.

How to change a setting

Three options, all equivalent. The setting ends up in the same place:

• In the app: open settings via the 10-tap gesture.
• Over HTTP: POST /settings with a JSON body. Only include the keys you want to change. See HTTP API.
• By directly editing the SharedPreferences file if you have root access on the device (rarely needed).

A few keys have type quirks; see "Gotchas" at the bottom.

Display & WebView

Key	Type	Default	What it does
webviewUrl	string	""	The page to load. Usually your HA URL.
ignoreSslErrors	bool	false	Skip SSL cert checks (for self-signed HA).
extendedJavascriptInterface	bool	false	Expose extra methods (event bindings, screensaver control) to the loaded page. See JavaScript Interface.

Brightness & screen

Key	Type	Default	What it does
automaticBrightness	bool	true	Track the light sensor. Linear ramp from minBrightness at 30 lux to full at 500+ lux.
brightness	int (0-255)	255	Fixed brightness when auto mode is off.
minBrightness	int (0-255)	48	Floor for auto-brightness. Stops the display going completely black in a dark room.
nightModeEnabled	bool	false	Red-channel-only tint for night viewing. Also exposed as a switch in Home Assistant and over POST /device/night_mode.

Screen saver

Key	Type	Default	What it does
screenSaver	bool	true	Enable the screensaver.
screenSaverDelay	int (sec)	45	Idle time before it kicks in. Minimum 5 in the UI; the API doesn't enforce that.
screenSaverId	int	0	0 = screen off, 1 = digital clock, 2 = clock + date, 3 = always-on display (AOD). See Screensavers.
screenSaverMinBrightness	int (0-255)	48	Brightness during the dimmed/clock screensaver. Ignored by AOD, which sets its own low brightness.
sleepOptimizationLevel	int	0	Power saving while asleep. 0 = none, 1 = standard (pause the WebView + throttle the CPU governor), 2 = aggressive (also slow MQTT/Bluetooth/voice). See Kiosk & Lite Mode.
wakeOnProximity	bool	true	Wake on proximity (only if the device has the sensor). Forced off on models without it.
proximityKeepAwakeSeconds	int	30	After a proximity wake, keep the screen on for this many seconds.
touchToWake	bool	(unset)	Wake on touch.

Inputs & buttons

Key	Type	Default	What it does
switchOnSwipe	bool	true	Toggle relay 0 on a vertical swipe over the WebView.
powerButtonAutoReboot	bool	true	Long-press the power button to reboot. Set to false to disable.
buttonRelayEnabled	bool	false	Map physical front buttons to relays. Only visible on XL/XLi.
buttonRelayMap0 ... buttonRelayMap3	int	-1	Per-button relay assignment. -1 = no mapping, 0/1 = relay index.

HTTP server

Key	Type	Default	What it does
httpServer	bool	true	Start the REST server on port 8080. Port isn't configurable. No auth, so keep it on a trusted LAN.

Remote access & debugging

Key	Type	Default	What it does
adbWifiEnabled	bool	false	ADB over Wi-Fi. Sets the adb TCP port to 5555 and restarts adbd, so you can adb connect <ip>:5555 once the display is wall-mounted with no USB reachable. Re-applied on every boot. Exposes the debug bridge to the whole LAN with no auth, so leave it off unless you need it. See Installation.

MQTT

Key	Type	Default	What it does
mqttEnabled	bool	false	Connect to a broker. Disabled unless broker/user/pass are all filled in.
mqttBroker	string	""	Broker host or IP.
mqttPort	int	1883	Broker port.
mqttUsername	string	""	Required. Connection refuses to start if blank.
mqttPassword	string	""	Required, same.
mqttDeviceId	string	auto	Client ID and topic prefix. Auto-generated as shellyelevate-XXXX (4 hex chars) on first launch.
mqttHomeAssistantDiscovery	bool	true	Publish HA discovery. Turn off for ioBroker or other non-HA brokers.
mqttRetainState	bool	(unset)	Retain state topics (temp, brightness, etc.) on the broker.

Voice assistant

Key	Type	Default	What it does
voiceAssistantEnabled	bool	false	Enable HA Assist. Needs the WebView URL to also be set.
voiceAssistantToken	string	""	HA long-lived access token.
voiceAssistantPipelineId	string	""	Specific pipeline. Empty means HA default.
voiceAssistantMaxRecordSeconds	int	10	Hard cap on a single listen turn.
voiceAssistantMuted	bool	(unset)	Mute state (also controllable over MQTT).
voiceWakeEnabled	bool	true	Wake-word detection. No-op without a model.
voiceWakeModelName	string	""	Filename of the .tflite model (without extension).
voiceWakeSensitivity	int (0-100)	50	50 = model's published threshold. Higher means more false triggers, lower means you miss more.
voiceWakeCooldownSec	int	5	Minimum gap between wake-word detections.
voiceWakeSoundEnabled	bool	true	Beep when detected and when listening ends.
voiceScoreBarEnabled	bool	false	Show a live score bar for debugging false triggers.
voiceWakeExperimentalModels	bool	false	Show community models from the TaterTotterson repo in the picker.

See Voice Assistant for the full story.

Bluetooth proxy

Key	Type	Default	What it does
bluetoothProxyEnabled	bool	false	Run an ESPHome-compatible BT proxy on port 6053.
bluetoothProxyName	string	"ShellyElevate"	Advertised mDNS name.

See Bluetooth Proxy.

Temperature compensation

The display heats up during normal use, which throws off the temperature sensor. ShellyElevate ships with a per-model static offset that handles this for the average case. If your readings are still off (especially if the room temperature varies a lot or you've enabled features that push CPU load up), there's a second, dynamic correction:

Key	Type	Default	What it does
dynamicTempOffsetEnabled	bool	false	Enable the dynamic offset.
dynamicTempOffsetZone	string	first found	Which thermal zone to use as the heat reference.
dynamicTempOffsetBaseline	float	40.0	Below this device temperature, no correction is applied.
dynamicTempOffsetK	float	0.3	How aggressively to correct.
publishThermalSensors	bool	false	Publish every thermal zone reading to MQTT (for HA dashboards).

The formula is: correction = k * max(0, device_temp - baseline) and gets subtracted from the reading.

Lite mode & device

Key	Type	Default	What it does
liteMode	bool	false	Skip the WebView; run only as a hardware exposer over MQTT/HTTP. See Kiosk & Lite Mode.
mediaEnabled	bool	false	Allow /media/play and friends to actually play audio.
device	string	auto	Detected device model (don't set manually).
settingEverShown	bool	false	Flips to true once the settings screen has been opened. Used to detect first launch.

Gotchas

• dynamicTempOffsetBaseline and dynamicTempOffsetK must be floats. The HTTP API will write them as float automatically, but if you POST a whole-number JSON value (like 40 instead of 40.0) it still gets stored as float, because the parser has explicit logic for these two keys. This is a fix for an older bug; nothing for you to worry about if you're using JSON.
• No auth on the HTTP API. Anyone on the LAN who can reach port 8080 can change every setting. Don't expose it.
• Voice assistant refuses to enable without a WebView URL. It uses the same URL as the WebView for its HA WebSocket connection.
• switchOnSwipe is hard-coded to relay 0. This isn't configurable from settings.
• Some settings are device-conditional. Proximity-related keys are forced off on models without a proximity sensor. The button-relay map is hidden unless the device has both buttons and relays.