{"id":23656358,"url":"https://github.com/lillian-alicia/bme680-mqtt","last_synced_at":"2026-04-18T17:35:34.893Z","repository":{"id":270044324,"uuid":"905831416","full_name":"lillian-alicia/bme680-mqtt","owner":"lillian-alicia","description":"A docker image which reads data from a Bosch BME680 atmospherics sensor, and sends the result to homeassistant via mqtt.","archived":false,"fork":false,"pushed_at":"2025-01-22T15:21:34.000Z","size":97,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-22T07:59:36.543Z","etag":null,"topics":["bme680","homeassistant","mqtt"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lillian-alicia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2024-12-19T15:56:43.000Z","updated_at":"2025-01-22T15:21:39.000Z","dependencies_parsed_at":"2025-08-11T00:18:40.308Z","dependency_job_id":"97e354dc-ea88-4a4d-b098-1a034538ed74","html_url":"https://github.com/lillian-alicia/bme680-mqtt","commit_stats":null,"previous_names":["lillian-alicia/bme680-mqtt"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lillian-alicia/bme680-mqtt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lillian-alicia%2Fbme680-mqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lillian-alicia%2Fbme680-mqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lillian-alicia%2Fbme680-mqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lillian-alicia%2Fbme680-mqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lillian-alicia","download_url":"https://codeload.github.com/lillian-alicia/bme680-mqtt/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lillian-alicia%2Fbme680-mqtt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31978268,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T17:30:12.329Z","status":"ssl_error","status_checked_at":"2026-04-18T17:29:59.069Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["bme680","homeassistant","mqtt"],"created_at":"2024-12-28T21:29:56.571Z","updated_at":"2026-04-18T17:35:34.876Z","avatar_url":"https://github.com/lillian-alicia.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bme680-mqtt\n\nA docker image which reads data from a Bosch BME680 atmospherics sensor, and sends the result to HomeAssistant via a MQTT broker.\n\n| ![Example HomeAssistant Device Page](assets/example-sensor-list.png) | ![Example HomeAssistant Device Page](assets/example-device-page.png) |\n| :------------------------------------------------------------------: | :------------------------------------------------------------------: |\n|          An example taken from the HomeAssistant dashboard.          |              The device in HomeAssistant's device view.              |\n\n## Example Compose File:\n\nThis example compose specification can be used to run the docker container:\n\n\u003e [!IMPORTANT]\n\u003e This repository and its associated docker image are currently private. Make sure to sign in with `docker login` before attempting to pull the image.\n\n```YAML\nservices:\n  bme680-mqtt:\n      image: ghcr.io/lillian-alicia/bme680-mqtt:1.0 # Select image version here\n\n      volumes:\n        - /dev/i2c-1:/dev/i2c-1 # Pass through the i2c device from the host.\n\n      environment:\n        MQTT_ADDR: 'example.broker.com'\n        MQTT_PORT: 1883 # Port for the MQTT broker, defaults to 1883.\n        MQTT_AUTH_MODE: 'none' # Replace with 'env' or 'file' if desired - see docs.\n        POLL_TIME: 60 # How often to send data via MQTT, in seconds.\n\n        MQTT_USERNAME: 'username' # The username and password for the MQTT\n        MQTT_PASSWORD: 'password' # broker if using MQTT_AUTH_MODE 'env'.\n\n      privileged: true\n```\n\n## MQTT Broker\n\nAn external MQTT broker is required in order for this container to send data to home assistant. This can be run locally as a container, on another host, or within homeassistant. I recommend using the [Eclipse Mosquitto](https://hub.docker.com/_/eclipse-mosquitto) broker, which can be run as a docker container.\n\nThe broker must support retained messages, and Quality of Service level 2 (QOS).\n\n### Authentication\n\nThis image supports both unauthenticated and authenticated connections to an MQTT broker, through the `MQTT_AUTH_MODE` environment variable (see [Environment Variables](README.md#environment-variables)).\n\nThe authentication mode can be set to one of three options:\n\n- `none` - No authentication. Any provided credentials will be ignored.\n- `env` - Authentication credentials are supplied through environment variables (`MQTT_USERNAME` and `MQTT_PASSWORD`).\n- `file` - Authentication credentials are supplied in JSON format, in a file bind-mounted to the container.\n\nIf using the `file` auth mode, the credentials should be supplied in the following format:\n\n```json\n{ \"username\": \"USERNAME_HERE\", \"password\": \"YOUR_PASSWORD\" }\n```\n\n## HomeAssistant Discovery via MQTT\n\nHomeAssistant includes a discovery feature (see the [documentation](https://www.home-assistant.io/integrations/mqtt#mqtt-discovery) for more information), which subscribes to a specific MQTT topic. Devices transmitting via MQTT can send a discovery message to this topic, which HomeAssisant uses to automatically setup devices.\n\nThis docker image sends the following discovery message, which adds all of the data read from the BME680 sensor. Some parts of the message are set by [environment variables](README.md#environment-variables) - see below.\n\n**Coming Soon - Configuration to enable and disable selcted data.**\n\n```JSON\n{\n        \"device\"        :       {\n            \"name\"      :       \"[DEVICE_ID]\",\n            \"mf\"        :       \"Bosch\",\n            \"mdl\"       :       \"BME680\",\n            \"ids\"       :       \"BME680_[DEVICE_ID]\"\n        },\n        \"origin\"        :       {\n            \"name\"      :       \"bme680-mqtt\",\n            \"url\"       :       \"https://github.com/lillian-alicia/bme680-mqtt\",\n            \"sw\"        :       \"[Image Version Number]\"\n        },\n        \"components\"    :       {\n            \"temperature_celcius\":      {\n                \"name\"          :   \"Temperature °C\",\n                \"platform\"      :   \"sensor\",\n                \"device_class\"  :   \"temperature\",\n                \"unit_of_measurement\" : \"°C\",\n                \"suggested_display_precision\" : 2,\n                \"value_template\":   \"{{ value_json.temperature.celcius }}\",\n                \"unique_id\"     :   \"[DEVICE_ID]_temperature_celcius\"\n            },\n            \"temperature_farenheit\":      {\n                \"name\"          :   \"Temperature °F\",\n                \"platform\"      :   \"sensor\",\n                \"device_class\"  :   \"temperature\",\n                \"unit_of_measurement\" : \"°F\",\n                \"suggested_display_precision\" : 2,\n                \"value_template\":   \"{{ value_json.temperature.fahrenheit }}\",\n                \"unique_id\"     :   \"[DEVICE_ID]_temperature_fahrenheit\"\n            },\n            \"pressure\"          :      {\n                \"name\"          :   \"Pressure\",\n                \"platform\"      :   \"sensor\",\n                \"device_class\"  :   \"pressure\",\n                \"unit_of_measurement\" : \"hPa\",\n                \"suggested_display_precision\" : 1,\n                \"value_template\":   \"{{ value_json.pressure.pressure }}\",\n                \"unique_id\"     :   \"[DEVICE_ID]_pressure\"\n            },\n            \"humidity\"          :      {\n                \"name\"          :   \"Humidity\",\n                \"platform\"      :   \"sensor\",\n                \"device_class\"  :   \"humidity\",\n                \"unit_of_measurement\" : \"%\",\n                \"suggested_display_precision\" : 2,\n                \"value_template\":   \"{{ value_json.humidity.humidity }}\",\n                \"unique_id\"     :   \"[DEVICE_ID]_humidity\"\n            },\n            \"air_quality\"       :       {\n                \"name\"          :   \"Air Quality\",\n                \"platform\"      :   \"sensor\",\n                \"device_class\"  :   \"aqi\",\n                \"unit_of_measurement\" : \"none\",\n                \"suggested_display_precision\" : 0,\n                \"value_template\":   \"{{ value_json.airQuality.resistance }}\",\n                \"unique_id\"     :   \"[DEVICE_ID]_air_quality\"\n            }},\n        \"state_topic\"   :       \"[MQTT_TOPIC]\"\n    }\n```\n\n## Environment Variables\n\nThis docker image is designed to have user-friendly customisation. All of the necessary options are set using environment variables, and default to sane values.\n\n### Sensor Config\n\n- `I2C_ADDR` - The i2c address of the BME680 sensor. **Defaults to 0x76**, the standard address for i2C devices.\n- `POLL_TIME` - How frequently to send sensor data to HomeAssistant, in seconds. **Defaults to 60s**.\n\n### MQTT Broker Config\n\n- `MQTT_ADDR` - (**REQUIRED**) The IP address or hostname for the MQTT broker (see [MQTT Broker](README.md#mqtt-broker) for more information.)\n- `MQTT_PORT` - The port that the MQTT broker communicates on. **Defaults to 1883**, the default port used for MQTT.\n- `MQTT_AUTH_MODE` - The authentication method used to connect to the MQTT broker. This can be `none`, `env`, or `file` (see [Authentication](README.md#authentication)).\n- `MQTT_USERNAME` **(OPTIONAL)**\n\n### MQTT Topics Config\n\n- `MQTT_TOPIC` - The topic that MQTT messages containing sensor data are sent on. **Defaults to `bme680`**. This topic is automatically passed on to HomeAssistant when using discovery (see [Discovery](README.md#homeassistant-discovery-via-mqtt)).\n- `DISCOVERY_TOPIC` - The topic used by HomeAssistant for discovery. The default topic used in a HomeAssistant installation is `homeassistant`, however it can be changed by the user.\n- `DEVICE_ID` - The device name given to HomeAssistant via discovery. Note that the **device name** in HomeAssistant will be this ID, and the **device ID** will be `BME680_{DEVICE_ID}`.\n\n## Advanced Usage\n\n### Multiple Sensors\n\nThis project can be used to connect multiple BME680 sensors to HomeAssistant, provided that each instance of this container has a unique `DEVICE_ID` set as an [environment variable](README.md#environment-variables).\n\n### Disabling Discovery\n\n**Coming Soon...**\nDisabling use with HomeAssistant's discovery feature will soon be available by passing an environment variable to this container.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flillian-alicia%2Fbme680-mqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flillian-alicia%2Fbme680-mqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flillian-alicia%2Fbme680-mqtt/lists"}