Laravel Govee Laravel Package

Getting Started

This package, Laravel Govee, provides seamless integration with Govee smart home devices (e.g., Bluetooth-enabled sensors, lights, and environmental monitors). To get started:

1. Installation Run composer require chipneedham/laravel-govee and publish the config file with php artisan vendor:publish --provider="ChipNeedham\LaravelGovee\GoveeServiceProvider".

2. Configuration Set your Govee API key and device credentials in .env:

   GOVEE_API_KEY=your_api_key_here
   GOVEE_DEVICE_ID=your_device_id
   

3. First Use Case Fetch device data in a controller or command:

   use ChipNeedham\LaravelGovee\Facades\Govee;
   
   $deviceData = Govee::getDeviceData('your_device_id');
   return response()->json($deviceData);
   

   Check the Govee API docs for supported endpoints.

Implementation Patterns

Core Workflows

1. Device Management

   • List all paired devices:

     $devices = Govee::listDevices();
     

   • Register new devices via the Govee app and sync them programmatically.

2. Data Retrieval

   • Poll real-time metrics (e.g., temperature, humidity):

     $metrics = Govee::getMetrics('device_id', ['temperature', 'humidity']);
     

   • Use Laravel queues to avoid rate-limiting:

     Govee::fetchAndQueueMetrics('device_id', $metrics);
     

3. Event-Driven Updates Subscribe to device events (e.g., threshold alerts) using Laravel’s event system:

   Govee::listenForAlerts('device_id', function ($data) {
       event(new DeviceAlertReceived($data));
   });
   

Integration Tips

• Caching: Cache frequent requests (e.g., every 5 minutes) to reduce API calls:

  $data = Cache::remember("govee_{$deviceId}_metrics", now()->addMinutes(5), function () use ($deviceId) {
      return Govee::getMetrics($deviceId);
  });
  

• Logging: Enable debug logging in config/govee.php for troubleshooting:

  'log' => env('GOVEE_LOG_ENABLED', false),
  

Gotchas and Tips

Common Pitfalls

1. API Rate Limits

   • Govee’s free tier has strict limits (e.g., 1 request/second). Use exponential backoff:

     try {
         $data = Govee::getDeviceData($id);
     } catch (\ChipNeedham\LaravelGovee\Exceptions\RateLimitExceeded $e) {
         sleep(2); // Retry after delay
     }
     

2. Device Pairing

   • Devices must be paired via the Govee app first. The package does not handle Bluetooth pairing—only API interactions.

3. Timezone Mismatches

   • Govee returns timestamps in UTC. Convert to local time in Laravel:

     $localTime = $data['timestamp']->setTimezone('America/New_York');
     

Debugging

• Enable Verbose Logging: Set GOVEE_LOG_LEVEL=debug in .env to log raw API responses.
• Validate Device IDs: Ensure IDs match the format (e.g., E07A1B2C3D4). Use:

  if (!Govee::isValidDeviceId($deviceId)) {
      throw new \InvalidArgumentException("Invalid device ID format.");
  }
  

Extension Points

1. Custom Endpoints Extend the package by adding new methods to ChipNeedham\LaravelGovee\GoveeManager:

   // app/Providers/GoveeServiceProvider.php
   public function boot()
   {
       $this->app->make('ChipNeedham\LaravelGovee\GoveeManager')->extend('custom', function () {
           return new CustomGoveeClient();
       });
   }
   

2. Webhook Support For real-time updates, integrate with Govee’s webhook system (if available) and forward events to Laravel’s queue:

   // routes/web.php
   Route::post('/govee-webhook', [GoveeWebhookController::class, 'handle']);
   

3. Testing Use the GoveeFake facade for unit tests:

   Govee::shouldReceive('getDeviceData')->once()->andReturn($mockData);