{"id":28925988,"url":"https://github.com/pronovic/smartapp-sensortrack","last_synced_at":"2025-10-08T03:15:19.797Z","repository":{"id":37026124,"uuid":"502489392","full_name":"pronovic/smartapp-sensortrack","owner":"pronovic","description":"(Unmaintained) Historically track data from SmartThings sensors","archived":true,"fork":false,"pushed_at":"2025-01-14T23:28:15.000Z","size":660,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-12T00:43:18.398Z","etag":null,"topics":["grafana","influxdb","iot","sensors","smartapp","smartthings","systemd-service"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pronovic.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-06-12T01:03:04.000Z","updated_at":"2025-01-14T23:29:20.000Z","dependencies_parsed_at":"2024-04-16T16:28:55.725Z","dependency_job_id":"a5447422-9237-42ca-bacc-b1e36db20eec","html_url":"https://github.com/pronovic/smartapp-sensortrack","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/pronovic/smartapp-sensortrack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pronovic%2Fsmartapp-sensortrack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pronovic%2Fsmartapp-sensortrack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pronovic%2Fsmartapp-sensortrack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pronovic%2Fsmartapp-sensortrack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pronovic","download_url":"https://codeload.github.com/pronovic/smartapp-sensortrack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pronovic%2Fsmartapp-sensortrack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278882592,"owners_count":26062316,"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-10-08T02:00:06.501Z","response_time":56,"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":["grafana","influxdb","iot","sensors","smartapp","smartthings","systemd-service"],"created_at":"2025-06-22T11:11:15.564Z","updated_at":"2025-10-08T03:15:19.767Z","avatar_url":"https://github.com/pronovic.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SmartApp - Sensor Tracking\n\n[![license](https://img.shields.io/github/license/pronovic/smartapp-sensortrack)](https://github.com/pronovic/smartapp-sensortrack/blob/main/LICENSE)\n[![release](https://img.shields.io/github/v/release/pronovic/smartapp-sensortrack)](https://github.com/pronovic/smartapp-sensortrack/releases/latest)\n[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)\n\n_Note: As of January 2025, I have migrated my home automation infrastructure\nfrom SmartThings to Home Assistant, so I no longer use this software.  It does\nwork, and is still a decent example of how to write a compliant SmartApp using\nmy smartapp-sdk library.  However, the repository is archived and you should\nconsider this code to be unmaintained._\n\nThis is a SmartThings SmartApp that is used to capture data from SmartThings\ntemperature and humidity sensors and write it to an metrics database.\nOptionally, users with U.S.-based locations can choose to periodically capture\ncurrent temperature and humidity, sourced from the National Weather Service\nAPI.\n\nThe SmartApp is written in Python 3 using the [smartapp-sdk](https://pypi.org/project/smartapp-sdk/) package.  It \nis designed to run as a systemd user service writing data \nto [InfluxDB 2](https://docs.influxdata.com/influxdb/v2.2/) for later visualization with a\ntool such as [Grafana](https://grafana.com/).\n\n## Cautions \u0026 Limitations\n\n**_This is a developer-focused tool._**\n\nMy goal was to write something I could use myself on my own hardware, looking\nforward toward a possible later transition to AWS Lambda.  The code is well\ntested and functions properly, but I haven't spent a lot of effort on making\nthe installation process simple.  If you're not already comfortable with the\nUNIX command line, you may have a hard time getting this to work. \n\n**_Only one user can install the resulting SmartApp._**\n\nWhen following the instructions below, only the user that registers the\nSmartApp in the Developer Console will be able to use it.  Supporting broader\naccess to more users requires formal enrollment with SmartThings, and that\nprocess is outside the scope of this document.\n\n## Developer Documentation\n\nDeveloper documentation is found in [DEVELOPER.md](DEVELOPER.md).  See that\nfile for notes about how the code is structured, how to set up a development\nenvironment, etc.\n\n## Installing Prerequisites\n\nThe SmartApp needs to write to an [InfluxDB 2](https://docs.influxdata.com/influxdb/v2.2/) \ndatabase server.  You probably also want to install a data visualization tool that works\nwith InfluxDB, such as [Grafana](https://grafana.com/), although that is outside the\nscope of this documentation.\n\nInstall InfluxDB using the instructions on \nthe [InfluxDB downloads page](https://portal.influxdata.com/downloads/).  On a Debian\nserver, it's easiest to set up an apt source and install the Debian packages:\n\n```\n$ apt-get install influxdb2\n```\n\nWhen you're done, run the setup process:\n\n```\n$ sudo influx setup\n\u003e Welcome to InfluxDB 2.0!\n? Please type your primary username influx\n? Please type your password **************** \n? Please type your password again ****************\n? Please type your primary organization name iot\n? Please type your primary bucket name metrics\n? Please type your retention period in hours, or 0 for infinite 0\n? Setup with these parameters?\n  Username:          influx\n  Organization:      iot\n  Bucket:            metrics\n  Retention Period:  infinite\n Yes\nUser  Organization   Bucket\ninflux   iot      metrics\n```\n\nThen create a user to associate with your SmartApp:\n\n```\n$ sudo influx user create -n sensortrack -p somepassword -o iot\nID       Name\n09875e2210877000  sensortrack\n```\n\nFinally, create an authorization token that the sensortrack service can use for\nthe InfluxDB API:\n\n```\n$ sudo influx auth create -u sensortrack -o iot --write-buckets\nID       Description Token                                  User Name   User ID        Permissions\n\n09873344ad1b7000        BicWm9vn1Z0Th_o4fDkKWM2Ze6sTVAuKHnhov77XRdlmbkPPPPsssavvv3AH7UIKCg10d0RTB1lC8ipWXFtnjw==  sensortrack 09875e2210877000  [write:orgs/e7d4effddda1046f/buckets]\n```\n\nMake sure you save off all of the information you need for the later setup\nsteps.  You will need to know the URL and port (`:8086`) of the server, the\norganization (`iot`), the default bucket (`metrics`) and the token\n(`BicWm...`).\n\n## Installing the SmartApp Server\n\nThe software is distributed at GitHub.  To install the software, download the `.whl`\nfile for the [latest release](https://github.com/pronovic/smartapp-sensortrack/releases/latest),\nand install it using [pipx](https://pypa.github.io/pipx/), like:\n\n```\n$ pipx install --force --include-deps ./sensortrack-0.4.10-py3-none-any.whl\n```\n\n\u003e On Debian, I install pipx using: `apt-get install pipx --no-install-suggests --no-install-recommends`\n\nNext, configure the server.  Download the configuration bundle for the latest\nrelease.  Extract the tar file to your user configuration directory:\n\n```\n$ mkdir -p ~/.config\n$ tar zxvf sensortrack-config-0.4.10.tar.gz -C ~/.config\n```\n\nThis creates two directories within `~/.config`.  The `systemd` directory\ncontains configuration for the systemd user service that you will create\nshortly:\n\n```\nsystemd/user/sensortrack.service\n```\n\nThe webserver server runs on port 8080 by default.  If you want it to run on a\ndifferent port, edit `sensortrack.service` and make the appropriate adjustment.\n\nBy default, the webserver accepts connections on all interfaces (0.0.0.0).  Depending\non your infrastructure, you may be able to restrict this to 127.0.0.1 instead.  If\nyou want to do this, edit `sensortrack.service` and make the appropriate adjustment.\n\nThe `sensortrack` directory contains configuration for the sensortrack daemon process.\n\n```\nsensortrack/server/application.yaml\nsensortrack/server/logging.yaml\nsensortrack/server/server.env\n```\n\nEdit `server.env` and configure the connection to InfluxDB, using the values\nyou saved off above.\n\nNext, configure systemd:\n\n```\n$ sudo loginctl enable-linger \u003cyour-user\u003e    # restart user services at reboot\n$ systemctl --user enable sensortrack        # enable the sensortrack service\n$ systemctl --user start sensortrack         # start the sensortrack service\n$ systemctl --user status sensortrack        # show status for the sensortrack service\n```\n\nAt this point, the systemd service should be running.  Check that it is\nlistening:\n\n```\n$ curl -X GET http://localhost:8080/health\n$ curl -X GET http://localhost:8080/version\n```\n\nYou can also check the logs from the service:\n\n```\n$ journalctl --pager-end --user-unit sensortrack\n```\n\nIf you do need to change any of the systemd config files, make sure\nto reload them afterwards, before trying to do any further testing:\n\n```\n$ systemctl --user daemon-reload\n```\n\nFinally, reboot and confirm that the service starts automatically.  After\nreboot, use the same curl commands or check the logs to confirm everything is\nok.\n\n## Expose Your Endpoint\n\nAny SmartApp must have an endpoint that is available on the public internet\nover HTTPS.  The exact mechanism to accomplish this depends on what your\ninfrastructure looks like.  I already run an Apache webserver that supports\nHTTPS, so I used [this article](https://www.digitalocean.com/community/tutorials/how-to-use-apache-as-a-reverse-proxy-with-mod_proxy-on-debian-8) as \na starting point, and configured apache to proxy public requests to my\nsensortrack service.\n\nFirst, I enabled some modules:\n\n```\n$ a2enmod proxy\n$ a2enmod proxy_http\n$ a2enmod proxy_balancer\n$ a2enmod lbmethod_byrequests\n```\n\nThen, I added the following block to my existing Apache configuration:\n\n```\n# Sensor Tracking SmartApp\nProxyPreserveHost On\nProxyPass         \"/smartthings/myapp\" \"http://192.168.1.120:8080\"\nProxyPassReverse  \"/smartthings/myapp\" \"http://192.168.1.120:8080\"\n```\n\nWith this configuration in place, your SmartApp will be located at:\n\n```\nhttps://\u003cyourhost\u003e/smartthings/myapp/smartapp\n```\n\nThe same `/health` and `/version` endpoints you tested above will also be\nexposed, although SmartThings doesn't need to know about them.  Spot-check that\nthe external URL appears to be working.\n\n## Register Your SmartApp with SmartThings\n\nNow that you have a working webserver and you can look at the logs, you have\neverything you need to actually create and install the SmartApp in the\nSmartThings infrastructure.\n\nFirst, make sure that the webserver is running and that you have a console\nwindow open.  Watch the SmartApp logs with `journalctl`, as described above.\n\nNext, log into the [Developer Workspace](https://smartthings.developer.samsung.com/workspace/) with \nyour Samsung Account credentials.  Once there:\n\n- Click **New Project**\n- Click **Continue** under **Automation for the SmartThings App**\n- Enter a project name and click **Create Project**\n- In the next screen, click **Register App**\n- Choose the **Webhook Endpoint** option\n- Paste in the URL for your webhook and then proceed to the next page\n- Enter a name and description for the SmartApp\n- Under permissions, select the following and then proceed to the next page\n  - r:devices:*\n  - r:locations:*\n- Leave remaining optional configuration unchanged and click **Save**\n\nAt this point, you will get a client id and secret associated with your SmartApp.\nSave off these values, because you will not be able to see them again.\n\nSimultaneously, the SmartThings infrastructure will send a `CONFIRMATION` event\nto your webhook.  The application will handle that event and log an application\nID and a confirmation URL that you can see using `journalctl`.  Copy out that\nURL and view it in a browser.  This step confirms that you control the webhook.\n\nOnce you've done the initial connection here and the webhook has been\nrecognized, you have to mark your app as **Deployed to test**, and then you'll\nbe able to try installing it.\n\n## Install the SmartApp\n\nSamsung makes it difficult to install non-standard SmartApps. See this [community thread](https://community.smartthings.com/t/faq-did-we-lose-the-ability-to-add-custom-smartapps-after-the-app-update-of-june-2021/227734) for \na discussion.  The process described below worked for me in June of 2022.\n\n\u003e _Note:_ If you haven't logged into the Developer Workspace at least once, this\n\u003e won't work.  But if you followed the instructions above, that should already\n\u003e be taken care of.\n\nFollow the instructions to [Enable Developer Mode in the SmartThings App](https://developer-preview.smartthings.com/docs/devices/test-your-device/#enable-developer-mode-in-the-smartthings-app):\n\n- Tap the **Menu** tab on the bottom navigation bar\n- Tap the **Settings gear** icon \n- The SmartThings settings menu will appear\n- Long-press **About SmartThings** for 5 seconds.\n- A developer mode toggle will appear in the settings menu immediately below where you were long-pressing (it might not be obvious)\n- Click the toggle to enable **Developer Mode**.\n- You will be prompted to restart the SmartThings app\n\nOnce you've enabled Developer Mode and restarted, you need to find your\nSmartApp:\n\n- Tap on the **Routines** tab\n- Click on the little round icon that means **Discover** in the upper right of the screen (next to **+**)\n- Scroll all of the way to the bottom to find your custom SmartApp, which should have whatever name you registered above\n- Click the SmartApp to configure it\n\nThis will immediately trigger a series of webhook `POST` requests to your\nwebserver.  If everything goes well, you will be prompted to configure the\nSmartApp, and you will get the option to choose which devices to collect data\nfrom.  If something goes wrong, you will get an error dialog in the app, and\nyou'll have to look in the `journalctl` logs to debug it.  If necessary, you\ncan adjust config files in `~/.config/sensortrack/server` to increase the log\nlevel or enable JSON logging (but note that JSON logging exposes secrets into\nyour log).\n\nOnce you are done configuring the SmartApp, it will subscribe to events from\nyour sensors.  As those events flow into the webhook, they will be recorded in\nInfluxDB.  There's no way to know exactly when the first event will be\ntriggered, so keep an eye on the logs and confirm that you don't see any\nerrors. You should see at least one event within the first hour or so,\ndepending on how you have your sensors configured.\n\n## Upgrading the SmartApp Server\n\nThe process is similar to installing.  Download the `.whl`\nfile for the [latest release](https://github.com/pronovic/smartapp-sensortrack/releases/latest),\nand install it using [pipx](https://pypa.github.io/pipx/), like:\n\n```\n$ pipx install --force --include-deps ./sensortrack-0.4.10-py3-none-any.whl\n```\n\n\u003e On Debian, I install pipx using: `apt-get install pipx --no-install-suggests --no-install-recommends`\n\nReload configuration and restart the systemd service::\n\n```\n$ systemctl --user daemon-reload\n$ systemctl --user restart sensortrack\n```\n\nAt this point, the systemd service should be running.  Check that it is\nlistening:\n\n```\n$ curl -X GET http://localhost:8080/health\n$ curl -X GET http://localhost:8080/version\n```\n\nYou can also check the logs from the service:\n\n```\n$ journalctl --pager-end --user-unit sensortrack\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpronovic%2Fsmartapp-sensortrack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpronovic%2Fsmartapp-sensortrack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpronovic%2Fsmartapp-sensortrack/lists"}