Fully Kiosk Rest API Integration in Home Assistant
10/25/20 Update - The isScreenOn property has been changed to screenOn in later versions of Fully Kiosk. Check your JSON output for the correct name
In this post I'll show how I exposed the backlight of my crappy old Android tablet as a Light in Home Assistant using the Fully Kiosk Rest API. Next, using sensors in HA, I was able to automate screen brightness based on presence, ambient light, and motion. This approach should work on any Android tablet, eliminating the need for a microphone or built-in camera to detect motion and ambient light.
Fully Kiosk Android App
Fully Kiosk is popular in the HA community for displaying HA on an always-on Android tablet. Common problems with kiosk tablets include controlling screen power/brightness, monitoring battery info, etc. My exploration of these problems lead me to discover that Fully Kiosk has a very powerful Rest API which can be enabled to control of the tablet remotely.
Here are the settings you'll definitely want to set up:
- Start URL -> https://your.ha.ip.address:port/
- Keep Screen On -> Enable
- Unlock Screen -> Enable
- Screen Off Timer -> Set to zero (disabled)
- Enable Remote Administration -> Enabled
- Remote Admin Password -> your_password
- Remote Admin from Local Network -> Enable
Once you enable Remote Admin from Local Network, the settings menu will show an IP that you can visit on your web browser. Make sure you are able to get in and view the settings page. From there you can play around with the settings and get familiar with the API. Everything you can see is available via the API, and all settings can be manipulated using the same. Note that you will want to put the tablet on a static IP to prevent it from changing in the future.
Testing the Rest Commands
Once you have the app set up, you can test the Rest API by visiting this URL, replacing with your tablet's IP and the password you set up in the app:
http://your.tablet.ip.address:2323/?cmd=deviceInfo&type=json&password=your_passwordYou should get a JSON result back containing the full device info. Here is a sample from my own tablet (some values redacted for privacy):
{
"foregroundApp": "de.ozerov.fully",
"appVersionName": "1.37",
"ssid": "######################,",
"deviceManufacturer": "LENOVO",
"displayHeightPixels": 1200,
"ramTotalMemory": 1961115648,
"ip4": "192.168.1.11",
"displayWidthPixels": 1920,
"locationLongitude": ######################,
"deviceModel": "YOGA Tablet 2-830F",
"currentPage": "######################,",
"deviceName": "Yoga-Tablet 2",
"kioskLocked": false,
"isLicensed": true,
"locationAltitude": ######################,
"appVersionCode": 665,
"mac": "6c:5f:1c:db:9a:95",
"locationLatitude": ######################,
"isDeviceOwner": false,
"ip6": "FE80::6E5F:1CFF:FEDB:9A95",
"currentTabIndex": 0,
"plugged": true,
"keyguardLocked": false,
"startUrl": "######################,",
"isScreenOn": true,
"screenOrientation": 90,
"internalStorageTotalSpace": 11929907200,
"ramUsedMemory": 1203109888,
"appTotalMemory": 209715200,
"appFreeMemory": 187304953,
"internalStorageFreeSpace": 4656619520,
"batteryLevel": 14,
"appUsedMemory": 22410199,
"wifiSignalLevel": 9,
"ramFreeMemory": 758005760,
"externalStorageFreeSpace": -1,
"androidVersion": "5.0.1",
"kioskMode": false,
"currentFragment": "preferences",
"webviewUa": "######################,",
"externalStorageTotalSpace": -1,
"screenBrightness": 109,
"androidSdk": "21",
"hostname4": "192.168.1.11",
"deviceID": "######################",
"isDeviceAdmin": true,
"lastAppStart": "2/11/2020 1:51:22 PM",
"hostname6": "fe80::6e5f:1cff:fedb:9a95%wlan0",
"motionDetectorState": 0,
"maintenanceMode": false,
"locationProvider": "gps"
}We will use this data to get the current state of the screen backlight.
Now you can test the command to change screen brightness by running this URL in a web browser, replacing again your own IP and password:
http://your.tablet.ip.address:2323/?cmd=setStringSetting&key=screenBrightness&value=1&type=json&password=your_passwordYou should see the screen brightness go to minimum and your browser will show a response like this:
{"statustext":"Saved and applied Screen Brightness","status":"OK"}You can manipulate the value parameter between 1 and 255 to change the brightness on your tablet.
Now that these two Rest commands are working, we can integrate them into Home Assistant.
Home Assistant Integration
Now we can use the the two Rest commands to query and change the tablet backlight setting, and we can set it up as a Light to make the automation cleaner.
First we will add the Rest URLs to the secrets file. The URLs will contain passwords so it's best to keep them secret. Note that you can use template strings so that you can pass in dynamic variables for different commands. Make sure to replace the IP and password.
# Add to secrets.yaml
rest_url_kiosk_command: 'http://your.tablet.ip.address:2323/?cmd={{ cmd }}&key={{ key }}&value={{ value }}&type=json&password=your_password'
rest_url_kiosk_device_info: 'http://your.tablet.ip.address:2323/?cmd=deviceInfo&type=json&password=your_password'Next, set up the sensors that we will use to get the backlight state and brightness from the device. Note that you can pull any attribute you want from the device info. There are a bunch of attributes that could be useful for other automations, but for the backlight we are only interested in the following:
# Add to configuration.yaml
sensor:
- platform: rest
name: Kiosk Device Info
resource: !secret rest_url_kiosk_device_info
json_attributes:
- screenBrightness
- isScreenOn
value_template: 'OK'Now you can restart HA and you should have a new entity available called sensor.kiosk_device_info, with the two attributes listed. We will use this sensor to tell the light template what the current values are.
Next, we need to set up our REST Command to change the backlight settings. The following code will enable a new service, rest_command.kiosk_command which will take 3 parameters, cmd, key and value.
# Add to configuration.yaml
rest_command:
kiosk_command:
url: !secret rest_url_kiosk_commandAfter you restart HA you can test the service from the Service tool in home assistant, passing in the following parameters:
- cmd: setStringSetting
- key: screenBrightness
- value: [0-255]
If your service is working you should see the tablet screen change based on the value you are setting in the command. Note that the parameters are being passed into the template variables we defined in secrets.yaml. This way you can reuse the same rest_command for the entire API. Very handy!
Finally, we tie everything together using a template light. We will read the current values from the device info, and we will set the values using the rest_command service.
# Add to configuration.yaml
light:
- platform: template
lights:
tablet_backlight:
friendly_name: Tablet Backlight
value_template: '{{ states.sensor.kiosk_device_info.attributes["isScreenOn"] }}'
level_template: '{{ states.sensor.kiosk_device_info.attributes["screenBrightness"] }}'
turn_on:
service: rest_command.kiosk_command
data:
cmd: screenOn
turn_off:
service: rest_command.kiosk_command
data:
cmd: screenOff
set_level:
service: rest_command.kiosk_command
data_template:
cmd: setStringSetting
key: screenBrightness
value: '{{ brightness }}'Now restart HA one last time and you should have a new Light entity that controls the screen of your tablet just like it were a lightbulb!
Conclusion
Fully Kiosk was already an awesome app before I discovered the REST API. Now there are even more possibilities for automation using the custom rest_command service.
In my opinion, the Fully Kiosk REST API deserves it's own official integration due to the maturity of the API and the popularity of the app in the HA community. Until then, I have been able to set up some really useful automations using the rest commands, and I have given my crappy old tablet new life.