{"id":23752518,"url":"https://github.com/rwbl/domoticz-plugin-tinkerforge-ambientlightv2","last_synced_at":"2025-07-28T16:08:11.464Z","repository":{"id":156023979,"uuid":"238706646","full_name":"rwbl/domoticz-plugin-tinkerforge-ambientlightv2","owner":"rwbl","description":"Domoticz plugin to interact with the Tinkerforge Ambient Light Bricklet 2.0.","archived":false,"fork":false,"pushed_at":"2020-02-16T12:53:02.000Z","size":45,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-05-25T00:21:58.230Z","etag":null,"topics":["domoticz","domoticz-plugin","tinkerforge","tinkerforge-alv2","tinkerforge-python-binding"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rwbl.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-02-06T14:25:42.000Z","updated_at":"2020-02-16T12:53:04.000Z","dependencies_parsed_at":null,"dependency_job_id":"51f34928-e3e5-4cd2-8171-f4bd2ea7d705","html_url":"https://github.com/rwbl/domoticz-plugin-tinkerforge-ambientlightv2","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rwbl/domoticz-plugin-tinkerforge-ambientlightv2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rwbl%2Fdomoticz-plugin-tinkerforge-ambientlightv2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rwbl%2Fdomoticz-plugin-tinkerforge-ambientlightv2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rwbl%2Fdomoticz-plugin-tinkerforge-ambientlightv2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rwbl%2Fdomoticz-plugin-tinkerforge-ambientlightv2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rwbl","download_url":"https://codeload.github.com/rwbl/domoticz-plugin-tinkerforge-ambientlightv2/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rwbl%2Fdomoticz-plugin-tinkerforge-ambientlightv2/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267543402,"owners_count":24104569,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["domoticz","domoticz-plugin","tinkerforge","tinkerforge-alv2","tinkerforge-python-binding"],"created_at":"2024-12-31T17:53:12.501Z","updated_at":"2025-07-28T16:08:11.454Z","avatar_url":"https://github.com/rwbl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# domoticz-plugin-tinkerforge-ambientlightv2\n[Domoticz](https://www.domoticz.com/) plugin to interact with the [Tinkerforge Ambient Light Bricklet 2.0](https://www.tinkerforge.com/en/doc/Hardware/Bricklets/Ambient_Light_V2.html#ambient-light-v2-bricklet).\n\n# Objectives\n* To read the illuminance of the Tinkerforge Ambient Light Bricklet 2.0.\n* To learn how to write generic Python plugin(s) for the Domoticz Home Automation system communicating with [Tinkerforge](http://www.tinkerforge.com) Building Blocks. This plugin espcially focus on using the Domoticz Hearbeat.\n\n**NOTE**: The Ambient Light Bricklet 2.0 is discontinued and is no longer sold. The Ambient Light Bricklet 3.0 is the recommended replacement.\n\n_Abbreviations_: TF=Tinkerforge, Bricklet=Tinkerforge Ambient Light Bricklet 2.0, GUI=Domoticz Web UI.\n\n## Solution\nA Domoticz Python plugin named \"Tinkerforge Ambient Light Bricklet 2.0\" gets in regular polling intervals the illuminance.\nThe Domoticz device created is from Type: Lux, SubType: Lux.\nThe bricklet is connected to a Tinkerforge Master Brick which is direct connected via USB with the Domoticz Home Automation system.\nThe Domoticz Home Automation system is running on a Raspberry Pi 3B+.\n\n### Logic\nThe only function of the plugin is to get the illuminance measured (Lux) from the bicklet and update the Domoticz device (Lux).\nThis is triggered by the plugin polling interval (s) parameter based on the Domoticz default heartbeat (every 10s).\nThe action taken is: IP connection \u003e Create device object \u003e get the illuminance \u0026 update Domoticz device \u003e IP disconnect.\n\nIf \"(HeartbeatCounter x HeartbeatInterval ) % PollingInterval = 0\" then the illuminance is read \u0026 updated.\n* HeartbeatCounter - increases every 10s heartbeat\n* HeartbeatInterval - 10s\n* PollingIntervaland - plugin parameter (default 300s = 5 min)\n\nExamples trigger action:\n* every minute (60s = 6 x 10s heartbeats] = (6 x 10) % 60 = 0\n* every 5 minutes (300s = 30 x 10s heartbeats] = (30 x 10) % 300 = 0\n\nAny additional logic to be defined in Domoticz. Either by additional devices or scripts.\nExamples\n* Switch light(s) on, if illuminance below certain threshold.\nMore see section \"dzVents Lua Automation Script Examples\".\n\n## Hardware Parts\n* Raspberry Pi 3B+ [(Info)](https://www.raspberrypi.org)\n* Tinkerforge Master Brick 2.1 FW 2.4.10 [(Info)](https://www.tinkerforge.com/en/doc/Hardware/Bricks/Master_Brick.html#master-brick)\n* Tinkerforge Ambient Light Bricklet 2.0 FW 2.0.2 [(Info)](https://www.tinkerforge.com/en/doc/Hardware/Bricklets/Ambient_Light_V2.html#ambient-light-v2-bricklet)\n\n## Software\n* Raspberry Pi Raspian Debian Linux Buster 4.19.93-v7+ #1290\n* Domoticz Home Automation System V4.11717 (beta) \n* Tinkerforge Brick Daemon 2.4.1, Brick Viewer 2.4.11\n* Tinkerforge Python API-Binding 2.1.24 [(Info)](https://www.tinkerforge.com/en/doc/Software/Bricklets/AmbientLightV2_Bricklet_Python.html#ambient-light-v2-bricklet-python-api)\n* Python 3.7.3, GCC 8.2.0\n* The versions for developing this plugin are subject to change.\n\n## Quick Steps\nFor implementing the Plugin on the Domoticz Server running on the Raspberry Pi.\nSee also Python Plugin Code (well documented) **plugin.py**.\n\n## Test Setup\nFor testing this plugin, the test setup has a Master Brick with Ambient Light Bricklet 2.0 connected to port C.\nOn the Raspberry Pi, it is mandatory to install the Tinkerforge Brick Daemon and Brick Viewer following [these](https://www.tinkerforge.com/en/doc/Embedded/Raspberry_Pi.html) installation instructions (for Raspian armhf).\nStart the Brick Viewer and action:\n* Update the devices firmware\n* Obtain the UID of the RGB LED Bricklet 2.0 as required by the plugin (i.e. Jng).\n\n## Domoticz Web GUI\nOpen windows GUI Setup \u003e Hardware, GUI Setup \u003e Log, GUI Setup \u003e Devices\nThis is required to add the new hardware with its device and monitor if the plugin code is running without errors.\nIt is imporant, that the GUI \u003e Setup \u003e Hardware accepts new devices!\n\n## Create folder\nThe folder name is the same as the key property of the plugin (i.e. plugin key=\"tfambientlightlv2\").\n```\ncd /home/pi/domoticz/plugins/tfambientlightlv2\n```\n\n## Create the plugin\nThe plugin has a mandatory filename **plugin.py** located in the created plugin folder.\nDomoticz Python Plugin Source Code: see file **plugin.py**.\n\n## Install the Tinkerforge Python API\nThere are two options.\n\n### 1) sudo pip3 install tinkerforge\nAdvantage: in case of binding updates, only a single folder must be updated.\nCheck if a subfolder tinkerforge is created in folder /usr/lib/python3/dist-packages.\n**Note**\nCheck the version of \"python3\" in the folder path. This could also be python 3.7 or other = see below.\n\n**If for some reason the bindings are not installed**\nUnzip the Tinkerforge Python Binding into the folder /usr/lib/python3/dist-packages.\n_Example_\nCreate subfolder Tinkerforge holding the Tinkerforge Python Library\n```\ncd /home/pi/tinkerforge\n```\nUnpack the latest python bindings into folder /home/pi/tinkerforge\nCopy /home/pi/tinkerforge to the Python3 dist-packges\n```\nsudo cp -r /home/pi/tinkerforge /usr/lib/python3/dist-packages/\n```\n\nIn the Python Plugin code amend the import path to enable using the Tinkerforge libraries\n```\nfrom os import path\nimport sys\nsys.path\nsys.path.append('/usr/local/lib/python3.7/dist-packages')\n```\n\n### 2) Install the Tinkerforge Python Bindings in a subfolder of the plugin and copy the binding content.\nDisadvantage: Every Python plugin using the Tinkerforge bindings must have a subfolder tinkerforge.\nIn case of binding updates,each of the tinkerforge plugin folders must be updated.\n/home/pi/domoticz/plugins/soilmoisturemonitor/tinkerforge\n\nThere is no need to amend the path as for option 1.\n\nFor either ways, the bindings are used like:\n```\nimport tinkerforge\nfrom tinkerforge.ip_connection import IPConnection\nfrom tinkerforge.bricklet_ambient_light_v2 import BrickletAmbientLightV2\n```\n**Note**\nAdd more bindings depending Tinkerforge bricks \u0026 bricklets used.\n\nEnsure to update the files in case of newer Tinkerforge Python Bindings.\n\n## Make plugin.py executable\n```\ncd /home/pi/domoticz/plugins/tfambientlightlv2\nchmod +x plugin.py\n```\n\n## Restart Domoticz\nRestart Domoticz to find the plugin:\n```\nsudo systemctl restart domoticz.service\n```\n\n**Note**\nWhen making changes to the Python plugin code, ensure to restart Domoticz and refresh any of the Domoticz Web GUI's.\n\n## Domoticz Add Hardware Tinkerforge Ambient Light Bricklet 2.0\n**IMPORTANT**\nPrior adding, set GUI Stup \u003e Settings \u003e Hardware the option to allow new hardware.\nIf this option is not enabled, no new devices are created assigned to this hardware.\nCheck in the Domoticz log as error message Python script at the line where the new device is used\n(i.e. Domoticz.Debug(\"Device created: \"+Devices[1].Name))\n\nIn the GUI Setup \u003e Hardware add the new hardware \"Tinkerforge Ambient Light Bricklet 2.0\".\n\n## Add Hardware - Check the Domoticz Log\nAfter adding,ensure to check the Domoticz Log (GUI Setup \u003e Log)\n\n## Example Domoticz Log Entry Adding Hardware with Debug=True\n```\n2020-02-06 10:55:15.156 (TFALV2) Debug logging mask set to: PYTHON PLUGIN QUEUE IMAGE DEVICE CONNECTION MESSAGE ALL \n2020-02-06 10:55:15.156 (TFALV2) 'HardwareID':'8' \n2020-02-06 10:55:15.156 (TFALV2) 'HomeFolder':'/home/pi/domoticz/plugins/tfambientlightlv2/' \n2020-02-06 10:55:15.156 (TFALV2) 'StartupFolder':'/home/pi/domoticz/' \n2020-02-06 10:55:15.156 (TFALV2) 'UserDataFolder':'/home/pi/domoticz/' \n2020-02-06 10:55:15.156 (TFALV2) 'Database':'/home/pi/domoticz/domoticz.db' \n2020-02-06 10:55:15.156 (TFALV2) 'Language':'en' \n2020-02-06 10:55:15.156 (TFALV2) 'Version':'1.0.0' \n2020-02-06 10:55:15.156 (TFALV2) 'Author':'rwbL' \n2020-02-06 10:55:15.156 (TFALV2) 'Name':'TFALV2' \n2020-02-06 10:55:15.156 (TFALV2) 'Address':'127.0.0.1' \n2020-02-06 10:55:15.156 (TFALV2) 'Port':'4223' \n2020-02-06 10:55:15.156 (TFALV2) 'Key':'tfambientlightlv2' \n2020-02-06 10:55:15.156 (TFALV2) 'Mode1':'yyc' \n2020-02-06 10:55:15.156 (TFALV2) 'Mode5':'60' \n2020-02-06 10:55:15.156 (TFALV2) 'Mode6':'Debug' \n2020-02-06 10:55:15.156 (TFALV2) 'DomoticzVersion':'4.11670' \n2020-02-06 10:55:15.156 (TFALV2) 'DomoticzHash':'f6af0fa0c' \n2020-02-06 10:55:15.156 (TFALV2) 'DomoticzBuildTime':'2020-02-02 12:21:53' \n2020-02-06 10:55:15.156 (TFALV2) Device count: 0 \n2020-02-06 10:55:15.156 (TFALV2) Creating new Device \n2020-02-06 10:55:15.156 (TFALV2) Creating device 'Ambient Light'. \n2020-02-06 10:55:15.157 (TFALV2) Device created: TFALV2 - Ambient Light \n2020-02-06 10:55:15.157 (TFALV2) SetBrickletConfiguration \n2020-02-06 10:55:15.153 Status: (TFALV2) Entering work loop. \n2020-02-06 10:55:15.154 Status: (TFALV2) Initialized version 1.0.0, author 'rwbL'\n```\n\n## Example Heartbeat Polling with Debug ON\n```\n2020-02-06 10:58:15.199 (TFALV2) onHeartbeat called. Counter=180 (Heartbeat=60) \n2020-02-06 10:58:15.199 (TFALV2) GetBrickletIlluminance: Unit 1, ID=80 \n2020-02-06 10:58:15.209 (TFALV2 - Ambient Light) Updating device from 0:'93.86' to have values 0:'99.38'. \n2020-02-06 10:58:15.338 (TFALV2) GetBrickletIlluminance: OK \n```\n## Example Heartbeat Polling with Debug OFF\nHeartbeat every minute.\n```\n2020-02-06 11:30:28.561 (TFALV2) Illuminance updated: 147.81 \n2020-02-06 11:31:28.562 (TFALV2) Illuminance updated: 150.28 \n2020-02-06 11:32:28.602 (TFALV2) Illuminance updated: 158.44 \n2020-02-06 11:33:28.596 (TFALV2) Illuminance updated: 179.66\n```\n\n## Example Heartbeat change from 60 to 300s [Mode5]\n```\n2020-02-06 11:00:42.459 (TFALV2) Debug logging mask set to: PYTHON PLUGIN QUEUE IMAGE DEVICE CONNECTION MESSAGE ALL \n2020-02-06 11:00:42.459 (TFALV2) 'HardwareID':'8' \n2020-02-06 11:00:42.459 (TFALV2) 'HomeFolder':'/home/pi/domoticz/plugins/tfambientlightlv2/' \n2020-02-06 11:00:42.459 (TFALV2) 'StartupFolder':'/home/pi/domoticz/' \n2020-02-06 11:00:42.459 (TFALV2) 'UserDataFolder':'/home/pi/domoticz/' \n2020-02-06 11:00:42.459 (TFALV2) 'Database':'/home/pi/domoticz/domoticz.db' \n2020-02-06 11:00:42.459 (TFALV2) 'Language':'en' \n2020-02-06 11:00:42.459 (TFALV2) 'Version':'1.0.0' \n2020-02-06 11:00:42.459 (TFALV2) 'Author':'rwbL' \n2020-02-06 11:00:42.459 (TFALV2) 'Name':'TFALV2' \n2020-02-06 11:00:42.459 (TFALV2) 'Address':'127.0.0.1' \n2020-02-06 11:00:42.459 (TFALV2) 'Port':'4223' \n2020-02-06 11:00:42.459 (TFALV2) 'Key':'tfambientlightlv2' \n2020-02-06 11:00:42.459 (TFALV2) 'Mode1':'yyc' \n2020-02-06 11:00:42.459 (TFALV2) 'Mode5':'300' \n2020-02-06 11:00:42.459 (TFALV2) 'Mode6':'Debug' \n2020-02-06 11:00:42.459 (TFALV2) 'DomoticzVersion':'4.11670' \n2020-02-06 11:00:42.459 (TFALV2) 'DomoticzHash':'f6af0fa0c' \n2020-02-06 11:00:42.459 (TFALV2) 'DomoticzBuildTime':'2020-02-02 12:21:53' \n2020-02-06 11:00:42.459 (TFALV2) Device count: 1 \n2020-02-06 11:00:42.459 (TFALV2) Device: 1 - ID: 80, Name: 'TFALV2 - Ambient Light', nValue: 0, sValue: '112.76' \n2020-02-06 11:00:42.460 (TFALV2) Device ID: '80' \n2020-02-06 11:00:42.460 (TFALV2) Device Name: 'TFALV2 - Ambient Light' \n2020-02-06 11:00:42.460 (TFALV2) Device nValue: 0 \n2020-02-06 11:00:42.460 (TFALV2) Device sValue: '112.76' \n2020-02-06 11:00:42.460 (TFALV2) Device LastLevel: 0 \n2020-02-06 11:00:42.460 (TFALV2) SetBrickletConfiguration\n```\n\n## dzVents Lua Automation Script Examples\n\n### Switch Light if Lux below threshold (dzVents Lua Automation Script)\nThis example runs the plugin on a Domoticz Development System (Ambient Light Bricklet 2.0 \u003e Master Brick \u003e Raspberry Pi 3B+).\nIf the measured Ambient Light Lux value is below a threshold, as set by a user variable, a Hue light, connected to a Domoticz Production System, is turned ON.\nIf the value is above threshold, the light is turned OFF again.\n```\n-- Tinkerforge Ambient Light Bricklet 2.0 Plugin - Test Script \n-- dzVents Automation Script: tfalv2_light_control\n-- Switch light(s) if the measued lux value is below threshold.\n-- The threshold is set by the user variable TH_AMBIENTLIGHT (Integer)\nlocal DOMOTICZURL = 'http://rpi-domoticz-ip:8080'\n-- Parameter On | Off\nlocal REQUESTURL = DOMOTICZURL .. '/json.htm?type=command\u0026param=switchlight\u0026idx=118\u0026switchcmd='\n\n-- NOT USED for now\n-- ensure the httpResponse name is unique across all dzVents scripts!\n-- use the scriptname plus Callback\nlocal HTTPCALLBACKNAME = 'RESTFALV2LIGHTCONTROL'\n\n-- idx of the devices\nlocal IDXAMBIENTLIGHT = 80         -- Type=Lux,Lux\nlocal IDXHUEMAKELAB = 118          -- Type=Light/Switch,Switch,Dimmer\n\n-- idx of the user variables (TH= threshold)\nlocal IDXTHAMBIENTLIGHT = 1   -- Type:Integer\n\nreturn {\n\ton = {\n\t\tdevices = {\n\t\t\tIDXAMBIENTLIGHT\n\t\t}\n\t},\n    data = {\n        -- keep the light state\n        lightstate = { initial = 0 }\n   },\n\n\texecute = function(domoticz, device)\n\t\t-- domoticz.log('Device ' .. device.name .. ' was changed', domoticz.LOG_INFO)\n\n        -- get the threshold from the user variable\n        local threshold = domoticz.variables(IDXTHAMBIENTLIGHT).value\n\n        -- switch light if the threshold \u003e 0\n        if threshold \u003e 0 then\n            -- switch the Light On\n\t    \tif domoticz.devices(IDXAMBIENTLIGHT).lux \u003c= threshold and domoticz.data.lightstate == 0 then\n                domoticz.openURL(REQUESTURL .. 'On')\n                domoticz.data.lightstate = 1\n    \t\tend\n\n            -- switch the Light Off\n\t\t    if domoticz.devices(IDXAMBIENTLIGHT).lux \u003e threshold and domoticz.data.lightstate == 1 then\n                domoticz.openURL(REQUESTURL .. 'Off')\n                domoticz.data.lightstate = 0\n\t\t    end\n            \n        end\n\n\tend\n}\n```\n\n#### Example Log\n```\n2020-02-06 11:50:28.809 (TFALV2) Illuminance updated: 182.48 \n2020-02-06 11:50:28.886 Status: dzVents: Info: Handling events for: \"TFALV2 - Ambient Light\", value: \"182.48\" \n2020-02-06 11:50:28.886 Status: dzVents: Info: ------ Start internal script: tfalv2_light_control: Device: \"TFALV2 - Ambient Light (TFALV2)\", Index: 80 \n2020-02-06 11:50:28.889 Status: dzVents: Info: ------ Finished tfalv2_light_control \n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frwbl%2Fdomoticz-plugin-tinkerforge-ambientlightv2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frwbl%2Fdomoticz-plugin-tinkerforge-ambientlightv2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frwbl%2Fdomoticz-plugin-tinkerforge-ambientlightv2/lists"}