Skip to content

BARCODE_SETUP.md

Latest commit

 

History

History
133 lines (93 loc) · 4.28 KB

BARCODE_SETUP.md

File metadata and controls

133 lines (93 loc) · 4.28 KB

Barcode/QR Code Setup Feature

This fork of CodeTimer-Mobile adds barcode scanning functionality to quickly configure the app with your Kimai2 server using QR codes generated by the Kimai Mobile Setup plugin.

What's New

  • QR Code Scanner: Scan QR codes from the Kimai Mobile Setup plugin to automatically configure server URL and API token
  • Camera Support: Added camera permissions for Android devices
  • One-Click Setup: No more manual typing - just scan and save!

Prerequisites

  1. Kimai2 Server with the Kimai Mobile Setup Bundle plugin installed
    • This plugin is required to generate QR codes for mobile setup
    • Install from: cloudrizon/kimai-mobile-setup-bundle
    • Without this plugin, you can still use the app by manually entering server URL and API token
  2. Mobile device with camera support (Android)
  3. API Token generated from your Kimai user profile

How to Use

Step 1: Generate QR Code on Your Kimai Server

  1. Log in to your Kimai2 instance (e.g., https://time.aristotleaccounting.ca)
  2. Navigate to your user profile settings
  3. Go to the "Mobile Setup" or "API Token" section
  4. Create a new API token (if you haven't already)
  5. A QR code will be displayed containing your server URL, email, and API token

Step 2: Scan QR Code in the Mobile App

  1. Open the CodeTimer Mobile app
  2. Navigate to Settings (gear icon)
  3. Click the "Scan QR Code" button (green button with QR code icon)
  4. Allow camera permissions when prompted
  5. Point your camera at the QR code displayed on your Kimai server
  6. The app will automatically fill in:
    • Server URL (host)
    • API Token
  7. Click "Save" to store the settings

Step 3: Start Tracking Time

Once configured, you can immediately start tracking your time entries!

QR Code Format

The QR code generated by the Kimai Mobile Setup plugin contains JSON data with the following structure:

{
  "serverURL": "https://your-kimai-instance.com",
  "userEmail": "your-email@example.com",
  "apiToken": "your-api-token-here"
}

Building the App

Install Dependencies

npm install
cordova platform add android

Build for Android

cordova build android

Run on Device

cordova run android

Technical Changes

Files Modified

  1. www/setting.html - Added "Scan QR Code" button to settings page
  2. www/js/setting.js - Implemented scanQRCode() function with barcode scanner integration
  3. config.xml - Added camera permissions for Android platform
  4. package.json - Added phonegap-plugin-barcodescanner dependency

Dependencies Added

  • phonegap-plugin-barcodescanner (v8.1.0) - Cross-platform barcode/QR code scanner

Scanner Configuration

The scanner is configured with the following options:

  • QR_CODE format only
  • Front camera disabled (uses back camera)
  • Flip camera button enabled
  • Torch/flashlight button enabled
  • Portrait orientation
  • Custom prompt message

Troubleshooting

"Barcode scanner is not available"

  • Make sure you're running on a physical device (not browser)
  • Camera permissions must be granted

"Invalid QR Code format"

  • Ensure you're scanning a QR code from the Kimai Mobile Setup plugin
  • The QR code must contain valid JSON with serverURL and apiToken fields

"Failed to parse QR Code data"

  • The QR code may be damaged or not from a valid Kimai Mobile Setup plugin
  • Try regenerating the QR code on your Kimai server

Camera Not Working

  • Check that camera permissions are granted in Android settings
  • Verify your device has a working camera

Contributing

This is a local fork of the CodeTimer-Mobile project with barcode scanning enhancements.

License

Apache-2.0 (same as original CodeTimer-Mobile project)

Credits & Acknowledgments

  • Original CodeTimer-Mobile by Martin Lačný - Owly
  • QR Code Scanner Feature implementation for Aristotle Accounting
  • cloudrizon - Creator of the Kimai Mobile Setup Bundle plugin, which this scanner integrates with
  • phonegap-plugin-barcodescanner (v8.1.0) by PhoneGap team