Owasys Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Run composer require coffeebike/owasys-bundle in your Laravel project (note: this is a Symfony bundle, so you’ll need to bridge it via Symfony Bridge or use it in a Symfony-based Laravel app like Laravel Symfony).

2. Enable the Bundle Since Laravel doesn’t use AppKernel.php, register the bundle in config/app.php under the extra.bundles key (if using Symfony components) or via a custom service provider:

   // config/app.php
   'extra' => [
       'bundles' => [
           CoffeeBike\OwasysBundle\CoffeeBikeOwasysBundle::class,
       ],
   ],
   

   Alternative: Create a Laravel service provider to initialize the bundle:

   php artisan make:provider OwasysServiceProvider
   

   Then register it in config/app.php and initialize the bundle in the provider’s boot() method.

3. First Use Case: MQTT Connection Configure the bundle via config/packages/coffee_bike_owasys.yaml (create the file if missing):

   coffee_bike_owasys:
       mqtt:
           host: 'your-mqtt-broker'
           port: 1883
           username: 'your-username'
           password: 'your-password'
           client_id: 'owasys-laravel-client'
   

   Trigger the MQTT connection in a controller or command:

   use CoffeeBike\OwasysBundle\Service\OwasysMqttService;
   
   public function connectOwasys(OwasysMqttService $mqttService) {
       $mqttService->connect();
   }
   

Implementation Patterns

Workflows

1. Device Communication

   • Publish Commands: Send MQTT messages to the OWA11 device (e.g., GPS tracking requests, firmware updates):

     $mqttService->publish('owasys/device/command', json_encode(['action' => 'track']));
     

   • Subscribe to Events: Listen for device responses or telemetry:

     $mqttService->subscribe('owasys/device/telemetry', function ($payload) {
         $data = json_decode($payload, true);
         // Process GPS coordinates, battery status, etc.
     });
     

2. Event-Driven Architecture Use Laravel’s event system to decouple MQTT message handling:

   // In OwasysServiceProvider::boot()
   $mqttService = $this->app->make(OwasysMqttService::class);
   $mqttService->onTelemetryReceived(function ($data) {
       event(new OwasysTelemetryReceived($data));
   });
   

   Listen to events in your app:

   public function handle(OwasysTelemetryReceived $event) {
       // Log or process telemetry (e.g., store in DB, trigger alerts)
   }
   

3. Configuration Management

   • Override default MQTT settings via Laravel’s config:

     // config/owasys.php
     return [
         'mqtt' => [
             'host' => env('OWASYS_MQTT_HOST', 'localhost'),
         ],
     ];
     

   • Load the config in the bundle’s service provider:

     $this->app->singleton(OwasysMqttService::class, function ($app) {
         return new OwasysMqttService($app['config']['owasys.mqtt']);
     });
     

4. Command-Line Integration Create Artisan commands for MQTT management:

   php artisan make:command OwasysConnect
   

   public function handle() {
       $mqttService = $this->app->make(OwasysMqttService::class);
       $mqttService->connect();
       $this->info('Connected to Owasys device!');
   }
   

Gotchas and Tips

Pitfalls

1. Symfony vs. Laravel Compatibility

   • The bundle assumes Symfony’s Kernel and Container. Workarounds:
     • Use Laravel Symfony Bridge or wrap the bundle in a Laravel service provider.
     • Mock Symfony dependencies (e.g., EventDispatcher) if needed:

       $dispatcher = new Symfony\Component\EventDispatcher\EventDispatcher();
       $mqttService = new OwasysMqttService($dispatcher, $config);
       

2. MQTT Connection Issues

   • Debugging: Enable MQTT client logging:

     coffee_bike_owasys:
         mqtt:
             debug: true
     

   • Reconnection: Implement a retry mechanism for dropped connections:

     $mqttService->setOnConnectionLost(function () {
         $this->retryConnection();
     });
     

3. Message Serialization

   • The bundle expects JSON payloads. Validate incoming messages:

     $payload = $mqttService->getLastMessage();
     if (!is_string($payload) || json_decode($payload) === null) {
         throw new \RuntimeException('Invalid MQTT payload');
     }
     

4. Thread Safety

   • MQTT operations may block. Use Laravel queues for long-running tasks:

     dispatch(new ProcessOwasysTelemetry($data))->onQueue('owasys');
     

Tips

1. Extending Functionality

   • Custom Commands: Add device-specific commands by extending the bundle’s OwasysMqttService:

     class ExtendedOwasysService extends OwasysMqttService {
         public function sendFirmwareUpdate($filePath) {
             $this->publish('owasys/firmware', base64_encode(file_get_contents($filePath)));
         }
     }
     

   • Middleware: Intercept MQTT messages with a pipeline:

     $mqttService->setMessageMiddleware(function ($payload, callable $next) {
         $payload = str_replace('old', 'new', $payload); // Example transform
         return $next($payload);
     });
     

2. Testing

   • Mock the MQTT client for unit tests:

     $mockClient = $this->createMock(MqttClient::class);
     $mockClient->method('publish')->willReturn(true);
     $service = new OwasysMqttService($mockClient, $config);
     

   • Use PHP-MQTT’s test utilities for integration tests.

3. Performance

   • Batch telemetry data to reduce MQTT overhead:

     $batch = collect($telemetryData)->chunk(10);
     foreach ($batch as $chunk) {
         $mqttService->publish('owasys/batch', json_encode($chunk));
     }
     

4. Security

   • Validate MQTT topics to prevent injection:

     $allowedTopics = ['owasys/device/telemetry', 'owasys/device/command'];
     if (!in_array($topic, $allowedTopics)) {
         throw new \RuntimeException('Invalid MQTT topic');
     }
     

   • Use TLS for MQTT connections:

     coffee_bike_owasys:
         mqtt:
             ssl: true
             ca_file: '/path/to/ca.crt'
     

5. Monitoring

   • Track MQTT metrics (e.g., message count, latency) with Laravel Telescope:

     Telescope::addData([
         'owasys_messages_received' => $mqttService->getMessageCount(),
     ]);