Origo SDK

Flutter plugin for Origo SDK integration, providing mobile key functionality for access control systems including endpoint setup, reader scanning, and lock management.

Features

  • Initialize Origo SDK with service codes and app credentials
  • Set up endpoints using 16-digit activation codes
  • Scan for and connect to nearby readers
  • Open the closest available reader
  • Update endpoint configurations
  • Debug logging and log retrieval
  • Cross-platform support (Android & iOS)

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  origo_sdk: ^0.1.2

Then run:

flutter pub get

Platform Configuration

Android

Add the following permissions to your android/app/src/main/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Required for Bluetooth communication -->
    <uses-permission android:name="android.permission.BLUETOOTH" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    
    <!-- Required for Android 12+ Bluetooth permissions -->
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
    
    <!-- Required for file operations (SDK versions ≤ 32) -->
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="32"/>
    
    <!-- Required for notifications -->
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
    
    <!-- Required for network operations -->
    <uses-permission android:name="android.permission.INTERNET"/>

    <application>
        <!-- Your app configuration -->
    </application>
</manifest>

Local Repository Setup (Required)

The Origo SDK uses a local Maven repository to distribute the native Android SDK. You must replicate this repository structure in your project to consume the SDK properly.

Step 1: Create the repository directory structure

Create the following directory structure in your Android project root (same level as your app folder):

your_flutter_project/
├── android/
│   ├── app/
│   └── repo/
│       └── com/
│           └── example/
│               └── origo/
│                   └── 3.4.0/
│                       ├── origo-3.4.0.aar
│                       └── origo-3.4.0.pom

Step 2: Copy the required files

Copy the following files from the Origo SDK plugin to your project:

  1. AAR file: Copy origo-3.4.0.aar from the plugin's android/repo/com/example/origo/3.4.0/ directory to your android/repo/com/example/origo/3.4.0/ directory

  2. POM file: Copy origo-3.4.0.pom from the plugin's android/repo/com/example/origo/3.4.0/ directory to your android/repo/com/example/origo/3.4.0/ directory

iOS

Add the following keys to your ios/Runner/Info.plist:

<!-- Location permissions required by OrigoSDK -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app uses location services to detect nearby readers for secure access.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app uses location services to detect nearby readers for secure access, even when the app is in the background.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>This app uses location services to detect nearby readers for secure access, even when the app is in the background.</string>

<!-- Bluetooth permissions required by OrigoSDK -->
<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app uses Bluetooth to communicate with secure readers.</string>
<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to communicate with secure readers.</string>

<!-- Background modes for location and Bluetooth -->
<key>UIBackgroundModes</key>
<array>
    <string>location</string>
    <string>bluetooth-central</string>
    <string>bluetooth-peripheral</string>
    <string>background-processing</string>
</array>

Usage

Basic Setup

import 'package:origo_sdk/origo_sdk.dart';
import 'package:flutter/services.dart';

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final _origoSdk = OrigoSdk();
  bool _isInitialized = false;

  @override
  void initState() {
    super.initState();
    _initializeSDK();
  }

  Future<void> _initializeSDK() async {
    try {
      final isInitialized = await _origoSdk.initialize(
        'YOUR_ORIGO_LOCK_SERVICE_CODE',
        'YOUR_ORIGO_APP_ID',
        'YOUR_ORIGO_APP_ID_DESCRIPTION',
      );
      
      setState(() {
        _isInitialized = isInitialized;
      });
      
      if (isInitialized) {
        // Perform application startup
        final startupResult = await _origoSdk.applicationStartup();
        print('Startup result: $startupResult');
      }
    } on PlatformException catch (e) {
      print('Failed to initialize SDK: ${e.message}');
    }
  }

  Future<void> _setupEndpoint() async {
    try {
      final result = await _origoSdk.endpointSetup('YOUR_16_DIGIT_CODE');
      print('Endpoint setup result: $result');
    } on PlatformException catch (e) {
      print('Failed to setup endpoint: ${e.message}');
    }
  }

  Future<void> _startScanning() async {
    try {
      final result = await _origoSdk.startScan();
      print('Scan started: $result');
    } on PlatformException catch (e) {
      print('Failed to start scan: ${e.message}');
    }
  }

  Future<void> _openClosestReader() async {
    try {
      final result = await _origoSdk.openClosestReader();
      print('Open reader result: $result');
    } on PlatformException catch (e) {
      print('Failed to open reader: ${e.message}');
    }
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Origo SDK Example')),
        body: Padding(
          padding: EdgeInsets.all(16.0),
          child: Column(
            children: [
              Text('SDK Initialized: $_isInitialized'),
              SizedBox(height: 20),
              ElevatedButton(
                onPressed: _isInitialized ? _setupEndpoint : null,
                child: Text('Setup Endpoint'),
              ),
              ElevatedButton(
                onPressed: _isInitialized ? _startScanning : null,
                child: Text('Start Scanning'),
              ),
              ElevatedButton(
                onPressed: _isInitialized ? _openClosestReader : null,
                child: Text('Open Closest Reader'),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

Available Methods

Core Methods

  • initialize(String origoLockServiceCode, String origoAppId, String origoAppIdDescription) - Initialize the SDK
  • applicationStartup() - Perform application startup sequence
  • getEndpointSetupStatus() - Get current endpoint setup status
  • endpointSetup(String sixteenDigitCode) - Setup endpoint with activation code
  • endpointUpdate() - Update endpoint configuration

Reader Operations

  • startScan() - Start scanning for nearby readers
  • stopScan() - Stop scanning for readers
  • openClosestReader() - Open the closest available reader

Debugging

  • toggleLogging() - Toggle debug logging on/off
  • getLogs() - Retrieve debug logs

Permission Handling

⚠️ Important: The Origo SDK only checks if permissions are granted but does not request them. Your client application must handle permission requests before calling SDK methods that require them.

Required Permissions

Android:

  • BLUETOOTH_SCAN - Required for scanning nearby readers
  • BLUETOOTH_CONNECT - Required for connecting to readers
  • BLUETOOTH_ADVERTISE - Required for advertising capabilities
  • ACCESS_FINE_LOCATION or ACCESS_COARSE_LOCATION - Required for Bluetooth scanning on Android versions < 12

iOS:

  • Bluetooth permissions - Required for reader communication
  • Location permissions (when in use) - Required for reader detection

Implementation

Use packages like permission_handler to request permissions before calling SDK methods:

dependencies:
  permission_handler: ^11.3.1
  origo_sdk: ^0.1.2

import 'package:permission_handler.dart';

Future<void> _startScanning() async {
  // Request permissions before scanning
  Map<Permission, PermissionStatus> statuses = await [
    Permission.bluetoothScan,
    Permission.bluetoothConnect,
    Permission.bluetoothAdvertise,
    Permission.locationWhenInUse,
  ].request();

  bool allGranted = statuses.values.every(
    (status) => status == PermissionStatus.granted
  );

  if (!allGranted) {
    // Handle permission denial - guide user to settings if needed
    if (statuses.values.any((status) => status == PermissionStatus.permanentlyDenied)) {
      await openAppSettings();
    }
    return;
  }

  try {
    final result = await _origoSdk.startScan();
    print('Scan started: $result');
  } on PlatformException catch (e) {
    if (e.code == 'SCAN_ERROR' && e.message?.contains('permissions') == true) {
      // Permission was revoked, request again
      print('Permissions not granted: ${e.message}');
    }
  }
}

Error Handling

All methods may throw PlatformException. It's recommended to wrap calls in try-catch blocks:

try {
  final result = await _origoSdk.someMethod();
  // Handle success
} on PlatformException catch (e) {
  print('Error: ${e.message}');
  // Handle error
}

Requirements

  • Flutter >=3.3.0
  • Dart SDK >=3.6.0
  • Android API level 21+
  • iOS 11.0+

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and feature requests, please visit our GitHub repository.

Libraries

origo_sdk
origo_sdk_method_channel
origo_sdk_platform_interface