{"id":17511739,"url":"https://github.com/claws/bh1750","last_synced_at":"2025-04-05T23:10:19.175Z","repository":{"id":7725441,"uuid":"9091497","full_name":"claws/BH1750","owner":"claws","description":"An Arduino library for the digital light sensor breakout boards containing the BH1750FVI IC","archived":false,"fork":false,"pushed_at":"2023-08-18T20:16:03.000Z","size":380,"stargazers_count":257,"open_issues_count":16,"forks_count":107,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-03-29T22:07:15.400Z","etag":null,"topics":["arduino","arduino-library","light","lux","sensor"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/claws.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2013-03-29T03:25:38.000Z","updated_at":"2025-01-28T19:10:09.000Z","dependencies_parsed_at":"2024-01-15T18:46:07.668Z","dependency_job_id":"d259a4c5-63e2-41d7-a003-d305683ec64b","html_url":"https://github.com/claws/BH1750","commit_stats":{"total_commits":85,"total_committers":17,"mean_commits":5.0,"dds":0.7294117647058824,"last_synced_commit":"b6986b553faed246ee267801ca23ccaea038d7cc"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2FBH1750","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2FBH1750/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2FBH1750/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2FBH1750/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/claws","download_url":"https://codeload.github.com/claws/BH1750/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247411235,"owners_count":20934653,"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","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":["arduino","arduino-library","light","lux","sensor"],"created_at":"2024-10-20T05:09:49.977Z","updated_at":"2025-04-05T23:10:19.153Z","avatar_url":"https://github.com/claws.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BH1750\n\n[![Build Status](https://github.com/claws/BH1750/workflows/checks/badge.svg?branch=master)](https://github.com/claws/BH1750/actions)\u003cbr\u003e\n\nThis package contains an Arduino library for digital light sensor breakout boards containing the\nBH1750FVI IC.\n\nThe BH1750 board uses I2C for communication which requires two pins to\ncommunicate with the device. Configuring the I2C bus must be done in user code\n(not library code). This approach has been adopted so it can be done once and\nwill better support the various options for different platforms.\n\nA common module containing the BH1750 component is the GY-30 shown below.\n\n![GY-30 Module image](resources/gy30-module.jpg)\n\n\n## Overview\n\nThe BH1750 has six different measurement modes which are divided in two groups;\ncontinuous and one-time measurements. In continuous mode the sensor\ncontinuously measures lightness value. In one-time mode, the sensor makes only\none measurement and then goes into Power Down mode.\n\nEach mode has three different precisions:\n\n  - Low Resolution Mode - (4 lx precision, 16ms measurement time)\n  - High Resolution Mode - (1 lx precision, 120ms measurement time)\n  - High Resolution Mode 2 - (0.5 lx precision, 120ms measurement time)\n\nBy default, this library uses Continuous High Resolution Mode, but you can\nchange this to a different mode by passing the mode argument to\nBH1750.begin().\n\nWhen the One-Time mode is used your sensor will go into Power Down mode when\nit completes the measurement and you've read it. When the sensor is powered up\nagain it returns to the default mode which means it needs to be reconfigured\nback into One-Time mode. This library has been implemented to automatically\nreconfigure the sensor when you next attempt a measurement so you should not\nhave to worry about such low level details.\n\nUsually you will get an integer value which represent the lux equivalent.\n  - Low Resolution Mode - (generic range: 0.0 up to 54612.5 lux)\n  - High Resolution Mode - (generic range: 0.0 up to 54612.5 lux)\n  - High Resolution Mode 2 - (generic range: 0.0 up to 27306.25 lux)\n\nThe sensor itself returns a 16 bit unsigned integer. Therefore the maximum value is limited in general.\nThe standard conversion between the so called 'counts' to lux is 1/1.2, that means you get a smaller value.\nAs we use float, if an error occurs you will get a negative value.\n  - -1 no valid data was transmitted from the sensor\n  - -2 device is not configured\nOtherwise the measured counts are converted to lux and returned. If no advanced parameters are changed the maximum lux value is 54612.5 lx.\n\nAs the sensor counts impact of light in a specific time frame you could change this time frame.\nThis is needed if you use an overlay window or compensate for environmental influence like darkness.\nThis time frame is defined by a register which is called MTreg. Therefore you could choose a value between 32 and 254.\nThe default value is 69; keep in mind that the measurement time is changed accordingly.\n\nThe datasheet for the BH1750 chip can be obtained\n[here](https://www.mouser.de/datasheet/2/348/Rohm_11162017_ROHMS34826-1-1279292.pdf)[2011.11 Rev.D]\n\n\n## Installation [![arduino-library-badge](https://www.ardu-badge.com/badge/BH1750.svg?)](https://www.ardu-badge.com/BH1750)\n\n- **(For Arduino \u003e= 1.5.x)** Install this package by searching for it in the\n  Arduino Library Manager and then clicking ``install``. Alternatively, this\n  library can be installed manually by clicking \"Clone or download\" -\u003e \"Download ZIP\"\n  button. Then open Arduino IDE, click `Sketch -\u003e Include library -\u003e Add .ZIP library`\n  and select the downloaded archive.\n\n- **(For Arduino \u003c 1.5.x)** Download this package as an archive by clicking\n  \"Clone or download\" -\u003e \"Download ZIP\" button. Then extract the archive to\n  ``\u003cYour User Directory\u003e/My Documents/Arduino/libraries/`` folder and rename\n  it to `BH1750`. Restart IDE.\n\nThe following YouTube [video](https://youtu.be/ACTMQvPVMLs) (specifically from\n7:20 onwards) provides a good overview of manually installing this library and\nloading an example using the Arduino IDE.\n\n[![BH1750 Video Tutorial](https://img.youtube.com/vi/ACTMQvPVMLs/0.jpg)](https://youtu.be/ACTMQvPVMLs?t=437)\n\nInformation about the library installation process - https://www.arduino.cc/en/Guide/Libraries\n\n\n## Example\n\nAn example using the BH1750 library in conjunction with the GY-30 board\n(which contains the BH1750 component) is presented below. The example\ncode uses the BH1750 library in the default continuous high precision\nmode when making light measurements.\n\n### Wiring\n\nConnections:\n\n  - VCC -\u003e 3V3 or 5V\n  - GND -\u003e GND\n  - SCL -\u003e SCL (A5 on Arduino Nano, Uno, Leonardo, etc or 21 on Mega and Due, on esp8266 free selectable)\n  - SDA -\u003e SDA (A4 on Arduino Nano, Uno, Leonardo, etc or 20 on Mega and Due, on esp8266 free selectable)\n  - ADD -\u003e NC/GND or VCC (see below)\n\nThe ADD pin is used to set the sensor I2C address. By default (if ADD voltage\nless than 0.7 * VCC) the sensor address will be 0x23. If it has voltage\ngreater or equal to 0.7VCC voltage (e.g. you've connected it to VCC) the\nsensor address will be 0x5C.\n\nWiring up the GY-30 sensor board to an Arduino is shown in the diagram below.\n\n![Example wiring diagram image](resources/wiring-diagram-gy30-module.png)\n\n*The image above was created using [Fritzing](http://fritzing.org/home/) and\nthe GY-30 module was obtained from [here](http://omnigatherum.ca/wp/?p=6)*.\n\n### Code\n\nUpload the BH1750 test code to your Arduino.\n\n``` c++\n#include \u003cWire.h\u003e\n#include \u003cBH1750.h\u003e\n\nBH1750 lightMeter;\n\nvoid setup(){\n\n  Serial.begin(9600);\n\n  // Initialize the I2C bus (BH1750 library doesn't do this automatically)\n  // On esp8266 devices you can select SCL and SDA pins using Wire.begin(D4, D3);\n  Wire.begin();\n\n  lightMeter.begin();\n  Serial.println(F(\"BH1750 Test\"));\n\n}\n\nvoid loop() {\n\n  float lux = lightMeter.readLightLevel();\n  Serial.print(\"Light: \");\n  Serial.print(lux);\n  Serial.println(\" lx\");\n  delay(1000);\n\n}\n```\n\n### Output\n\nMoving the sensor to face more light results in the lux measurements increasing.\n```\nBH1750 Test\nLight: 70.0 lx\nLight: 70.0 lx\nLight: 59.0 lx\nLight: 328.0 lx\nLight: 333.0 lx\nLight: 335.0 lx\nLight: 332.0 lx\n```\n\n### More Examples\n\nThe ``examples`` directory contains more advanced use cases such as using different modes, I2C addresses and multiple Wire instances.\n\n## Developers\n\nThe following information is for developers of this library.\n### Code Format\n\nThe code in this project is formatted using ``clang-format`` tool.\n\nGood instructions for installing ``clang-format`` can be found\n[here](https://learn.adafruit.com/the-well-automated-arduino-library/formatting-with-clang-format)\n\nOnce the ``clang-format`` tool has been install you can then run the\nconvenience script (``ci/code-format.bash``) to check or apply the code\nformatting. The script should be run from the repo's top level directory.\n\n```shell\n$ ./ci/code-format.bash\n```\nThis script is also run as part of the project's continuous integration\nchecks.\n\nIf you make changes to code files then the code format can be applied\nby simply passing *apply* as an argument to the script.\n\n```shell\n$ ./ci/code-format.bash apply\n```\n\n### Code Linting\n\nThe code in this project is linted using ``arduino-lint``. The tool can be\ninstalled using the instructions [here](https://arduino.github.io/arduino-lint/latest/installation/).\n\nTo run the linter over the project use the command below.\n\n```shell\n$ arduino-lint --library-manager update --compliance strict\n```\n\nThe same command is run as part of the project's continuous integration\nchecks.\n\nIf errors or warnings are reported then fix them and re-run the script\nuntil they are resolved.\n\n### Build Locally\n\nThe code in this project can be built locally using the ``arduino-cli`` tool.\nThe tool can be installed using the instructions [here](https://github.com/arduino/arduino-cli#quickstart). Once you have the tool installed you can compile the\nexamples scripts using the convenience script (``ci/compile-examples.bash``).\n\n```shell\n$ ./ci/compile-examples.bash\n```\n\nThis script performs the same actions as the project's continuous integration\ncompile checks.\n\n### Release Process\n\n- Update ``library.json`` and ``library.properties`` version strings.\n- Create a new project release and use the new version number as tag. Click Publish.\n- Now wait about an hour for it to appear in the Arduino library manager.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaws%2Fbh1750","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclaws%2Fbh1750","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaws%2Fbh1750/lists"}