A Prometheus exporter for BH1750 ambient light sensors designed for Raspberry Pi

This repository contains a production-ready Prometheus exporter for the BH1750 ambient light sensors, optimized for use on Raspberry Pi devices. Built with Go, it provides reliable metrics collection with proper error handling.

Before you begin, ensure you have the necessary tools and dependencies installed:

• Go 1.16 or later: Required for building the project with Go modules:

sudo apt-get install golang

• Make: Required for building the source code:

sudo apt install make

Follow these steps to install the BH1750 Prometheus Exporter on your Raspberry Pi:

1. Clone the repository:

git clone https://github.com/guivin/bh1750-prometheus-exporter.git
cd bh1750-prometheus-exporter

2. Build the project:

make build

Or build manually:

go build -o bh1750-prometheus-exporter ./cmd/bh1750-prometheus-exporter

3. Install the binary (optional):

make install

4. Create a dedicated system user that belongs to the i2c group (for I2C bus access):

useradd --user-group --groups i2c --no-create-home --system --shell /usr/sbin/nologin bh1750-prometheus-exporter

5. Set up the configuration file. Copy the example configuration file and modify it according to your needs:

sudo cp examples/bh1750-prometheus-exporter.yml /etc/bh1750-prometheus-exporter.yml
sudo chown bh1750-prometheus-exporter:bh1750-prometheus-exporter /etc/bh1750-prometheus-exporter.yml
sudo chmod 0640 /etc/bh1750-prometheus-exporter.yml

Edit /etc/bh1750-prometheus-exporter.yml to configure:

• name: Sensor name for metrics labels
• i2c_bus: I2C bus number (usually 1 on Raspberry Pi)
• i2c_address: I2C address (0x23 default, 0x5C alternate)
• resolution: Measurement resolution (low, high, highest)
• listen_port: HTTP port for metrics endpoint (default: 8080)
• log_level: Logging level (debug, info, warn, error)

6. Integrate with systemd for easy service management:

sudo cp examples/bh1750-prometheus-exporter.service /etc/systemd/system
sudo systemctl daemon-reload
sudo systemctl enable bh1750-prometheus-exporter
sudo systemctl start bh1750-prometheus-exporter

Check service status:

sudo systemctl status bh1750-prometheus-exporter

The exporter exposes the following HTTP endpoints:

Retrieve the metrics from the exporter by querying the designated HTTP endpoint (adjust the port if your configuration differs):

curl http://localhost:8080/metrics

This command will output the current readings from your BH1750 sensors, making the data available for Prometheus scraping and subsequent analysis or visualization.

Add the following to your prometheus.yml to scrape metrics from the exporter:

scrape_configs:
  - job_name: 'bh1750'
    static_configs:
      - targets: ['raspberry-pi:8080']
    scrape_interval: 30s

Run the test suite:

make test

Generate test coverage report:

make test-coverage

This will create coverage.html that you can open in a browser to see detailed coverage information.

The project follows standard Go conventions:

bh1750-prometheus-exporter/
├── cmd/
│   └── bh1750-prometheus-exporter/    # Application entry point
├── internal/                        # Internal packages
│   ├── config/                      # Configuration management
│   ├── sensor/                      # BH1750 sensor interface and implementation
│   ├── collector/                   # Prometheus collector
│   └── logger/                      # Logging configuration
├── examples/                        # Example configuration files
│   ├── bh1750-prometheus-exporter.yml # Example config file
│   └── bh1750-prometheus-exporter.service # Example systemd service
├── testdata/                        # Test data files
├── go.mod                           # Go module definition
└── Makefile                         # Build automation

# Build the binary
make build

# Run tests
make test

# Clean build artifacts
make clean

# Tidy Go modules
make mod-tidy

If you see "permission denied" errors when accessing I2C bus:

# Ensure the user running the exporter is in the i2c group
sudo usermod -a -G i2c bh1750-prometheus-exporter

# Restart the service
sudo systemctl restart bh1750-prometheus-exporter

BH1750 sensors can occasionally fail to read. If you see frequent failures:

1. Check the wiring connections between the Raspberry Pi and the BH1750 sensor
2. Verify I2C is enabled on the Raspberry Pi (use sudo raspi-config)
3. Verify the sensor is detected with i2cdetect -y 1
4. Check the sensor is receiving proper 3.3V power

Check the service logs for errors:

sudo journalctl -u bh1750-prometheus-exporter -f

Common issues:

• Configuration file not found or invalid YAML
• Port already in use (change listen_port in config)
• Missing I2C permissions

If /metrics returns no BH1750 metrics:

1. Verify the sensor is properly connected
2. Check I2C address matches your sensor configuration
3. Review logs for sensor read errors
4. Test with debug log level: set log_level: debug in config

To manually test communication with the BH1750 sensor, use the following commands:

# Scan for devices on I2C bus 1
i2cdetect -y 1

# Power on the sensor
i2cset -y 1 0x23 0x01

# Start high-resolution one-time measurement (0x20)
i2cset -y 1 0x23 0x20

# Wait for measurement to complete
sleep 0.2

# Read 2 bytes directly (BH1750 doesn't use register addresses)
i2ctransfer -y 1 r2@0x23

If you get I/O errors during manual testing:

1. Power cycle the sensor - Disconnect and reconnect power to reset the sensor
2. Check wiring - Ensure SDA, SCL, VCC (3.3V), and GND are properly connected
3. Check kernel logs - Run dmesg | grep -i i2c for hardware-level errors