Accurate Step Counter #

A highly accurate Flutter plugin for step counting using native Android TYPE_STEP_DETECTOR sensor with accelerometer fallback. Zero external dependencies. Designed for reliability across foreground, background, and terminated app states.

✨ Features #

📱 Platform Support #

Note: This is an Android-only package. It won't crash on iOS but step detection won't work.

🚀 Quick Start #

1. Install #

dependencies:
  accurate_step_counter: ^1.2.0

2. Add Permissions #

In android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_HEALTH"/>
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>

3. Request Runtime Permission #

import 'package:permission_handler/permission_handler.dart';

// Request activity recognition (required)
await Permission.activityRecognition.request();

// Request notification (for Android 13+ foreground service)
await Permission.notification.request();

4. Start Counting! #

import 'package:accurate_step_counter/accurate_step_counter.dart';

final stepCounter = AccurateStepCounter();

// Listen to step events
stepCounter.stepEventStream.listen((event) {
  print('Steps: ${event.stepCount}');
});

// Start counting
await stepCounter.start();

// Stop when done
await stepCounter.stop();

// Clean up
await stepCounter.dispose();

📖 Complete Example #

import 'package:flutter/material.dart';
import 'package:accurate_step_counter/accurate_step_counter.dart';
import 'dart:async';

class StepCounterScreen extends StatefulWidget {
  @override
  State<StepCounterScreen> createState() => _StepCounterScreenState();
}

class _StepCounterScreenState extends State<StepCounterScreen> {
  final _stepCounter = AccurateStepCounter();
  StreamSubscription<StepCountEvent>? _subscription;
  int _steps = 0;
  bool _isRunning = false;

  @override
  void initState() {
    super.initState();
    _subscription = _stepCounter.stepEventStream.listen((event) {
      setState(() => _steps = event.stepCount);
    });
  }

  Future<void> _toggleTracking() async {
    if (_isRunning) {
      await _stepCounter.stop();
    } else {
      await _stepCounter.start();
    }
    setState(() => _isRunning = !_isRunning);
  }

  @override
  void dispose() {
    _subscription?.cancel();
    _stepCounter.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Step Counter')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('$_steps', style: const TextStyle(fontSize: 80, fontWeight: FontWeight.bold)),
            const Text('steps', style: TextStyle(fontSize: 24, color: Colors.grey)),
            const SizedBox(height: 40),
            ElevatedButton.icon(
              onPressed: _toggleTracking,
              icon: Icon(_isRunning ? Icons.stop : Icons.play_arrow),
              label: Text(_isRunning ? 'Stop' : 'Start'),
            ),
            TextButton(
              onPressed: () {
                _stepCounter.reset();
                setState(() => _steps = 0);
              },
              child: const Text('Reset'),
            ),
          ],
        ),
      ),
    );
  }
}

⚙️ Configuration #

Presets #

// For walking (default)
await stepCounter.start(config: StepDetectorConfig.walking());

// For running (more sensitive, faster detection)
await stepCounter.start(config: StepDetectorConfig.running());

// Sensitive mode (may have false positives)
await stepCounter.start(config: StepDetectorConfig.sensitive());

// Conservative mode (fewer false positives)
await stepCounter.start(config: StepDetectorConfig.conservative());

Custom Configuration #

await stepCounter.start(
  config: StepDetectorConfig(
    threshold: 1.2,                // Movement threshold (higher = less sensitive)
    filterAlpha: 0.85,             // Smoothing factor (0.0 - 1.0)
    minTimeBetweenStepsMs: 250,    // Minimum ms between steps
    enableOsLevelSync: true,       // Sync with OS step counter
    
    // Foreground service options (Android ≤10)
    useForegroundServiceOnOldDevices: true,
    foregroundNotificationTitle: 'Step Tracker',
    foregroundNotificationText: 'Counting your steps...',
  ),
);

Configuration Parameters #

🔧 API Reference #

AccurateStepCounter #

final stepCounter = AccurateStepCounter();

// Properties
stepCounter.stepEventStream       // Stream<StepCountEvent>
stepCounter.currentStepCount      // int
stepCounter.isStarted             // bool
stepCounter.isUsingForegroundService  // bool
stepCounter.currentConfig         // StepDetectorConfig?

// Methods
await stepCounter.start({config});    // Start detection
await stepCounter.stop();             // Stop detection
stepCounter.reset();                  // Reset count to zero
await stepCounter.dispose();          // Clean up resources

// Check sensor type
final isHardware = await stepCounter.isUsingNativeDetector();

// Terminated state sync (automatic, but can be manual)
stepCounter.onTerminatedStepsDetected = (steps, startTime, endTime) {
  print('Synced $steps missed steps');
};

StepCountEvent #

final event = StepCountEvent(stepCount: 100, timestamp: DateTime.now());

event.stepCount   // int - Total steps since start()
event.timestamp   // DateTime - When step was detected

🏗️ Architecture #

Overall Flow #

┌─────────────────────────────────────────────────────────────────┐
│                         Flutter App                              │
├─────────────────────────────────────────────────────────────────┤
│  AccurateStepCounter                                            │
│       ├── stepEventStream (real-time steps)                     │
│       ├── currentStepCount                                      │
│       └── onTerminatedStepsDetected (missed steps callback)     │
├─────────────────────────────────────────────────────────────────┤
│  NativeStepDetector (Dart)                                      │
│       ├── MethodChannel (commands)                              │
│       └── EventChannel (step events)                            │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                    Platform Channel
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│                     Android Native (Kotlin)                      │
├─────────────────────────────────────────────────────────────────┤
│  AccurateStepCounterPlugin                                      │
│       ├── NativeStepDetector.kt (sensor handling)               │
│       ├── StepCounterForegroundService.kt (Android ≤10)         │
│       └── SharedPreferences (state persistence)                 │
├─────────────────────────────────────────────────────────────────┤
│  Android Sensors                                                │
│       ├── TYPE_STEP_DETECTOR (primary - hardware)               │
│       └── TYPE_ACCELEROMETER (fallback - software)              │
└─────────────────────────────────────────────────────────────────┘

Step Detection Priority #

┌─────────────────────────────────────────────────┐
│            Check: TYPE_STEP_DETECTOR            │
│              (Hardware Sensor)                  │
└──────────────────────┬──────────────────────────┘
                       │
           ┌───────────▼───────────┐
           │     Available?        │
           └───────────┬───────────┘
                       │
          ┌────────────┴────────────┐
          │                         │
    ┌─────▼─────┐            ┌──────▼──────┐
    │    YES    │            │     NO      │
    └─────┬─────┘            └──────┬──────┘
          │                         │
┌─────────▼─────────┐    ┌─────────▼─────────┐
│  Hardware Step    │    │  Accelerometer    │
│  Detection        │    │  + Algorithm      │
│                   │    │                   │
│  • Best accuracy  │    │  • Low-pass filter│
│  • Battery saving │    │  • Peak detection │
│  • Event-driven   │    │  • Configurable   │
└───────────────────┘    └───────────────────┘

📱 App State Coverage #

How Each State is Handled #

Important: The persistent notification only appears on Android 10 and below. On Android 11+, no notification is shown because the native step detector works without needing a foreground service.

Detailed State Behavior #

🟢 Foreground State

App Active → NativeStepDetector → TYPE_STEP_DETECTOR → EventChannel → Flutter UI

• Real-time step counting with immediate updates
• Hardware-optimized detection
• Full access to all sensors

🟡 Background State

Android 11+:

App Minimized → Native detection continues → Steps buffered → UI updates when resumed

Android ≤10:

App Minimized → Foreground Service starts → Persistent notification shown
                    ↓
              Keeps CPU active via WakeLock
                    ↓
              Steps counted continuously
                    ↓
              Results polled every 500ms

🔴 Terminated State

Android 11+:

App Killed → OS continues counting via TYPE_STEP_COUNTER
                    ↓
             App Relaunched
                    ↓
       Compare saved count with current OS count
                    ↓
       Calculate missed steps
                    ↓
       Trigger onTerminatedStepsDetected callback

Android ≤10:

Foreground Service prevents true termination
                    ↓
       Service continues counting even if Activity destroyed
                    ↓
       No steps are ever missed

Terminated State Sync (Android 11+) #

// Automatic sync happens on start(), but you can handle it:
stepCounter.onTerminatedStepsDetected = (missedSteps, startTime, endTime) {
  print('You walked $missedSteps steps while app was closed!');
  print('From: $startTime to $endTime');
  
  // Optionally save to database or sync to server
  saveToDatabase(missedSteps, startTime, endTime);
};

🔋 Battery & Performance #

🐛 Debugging #

View Logs #

# All plugin logs
adb logcat -s AccurateStepCounter NativeStepDetector StepSync

# Only step events
adb logcat -s NativeStepDetector

Check Sensor Availability #

final isHardware = await stepCounter.isUsingNativeDetector();
print('Using hardware step detector: $isHardware');

❓ Troubleshooting #

📄 License #

MIT License - see LICENSE

🔗 Links #

• 📦 pub.dev
• 🐙 GitHub
• 📋 Changelog
• 🐛 Issues

Made with ❤️ for the Flutter community