Accurate Step Counter #

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

✨ Features #

Feature	Description
🎯 Native Detection	Uses Android's hardware-optimized `TYPE_STEP_DETECTOR` sensor
🔄 Accelerometer Fallback	Software algorithm for devices without step detector
💾 Hive Logging	Local persistent storage with source tracking (foreground/background/terminated)
🔥 Warmup Validation	Buffer steps during warmup, validate walking before logging
📦 Zero Dependencies	Only requires Flutter SDK + Hive
🔋 Battery Efficient	Event-driven, not polling-based
📱 All App States	Foreground, background, and terminated state support
⚙️ Configurable	Presets for walking/running + custom parameters

📱 Platform Support #

Platform	Status
Android	✅ Full support (API 19+)
iOS	❌ Not supported

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.3.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 #

Sweet & Simple - Works in ALL States (Foreground, Background, Terminated) #

import 'package:flutter/material.dart';
import 'package:flutter/foundation.dart';
import 'package:accurate_step_counter/accurate_step_counter.dart';
import 'package:permission_handler/permission_handler.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: const StepCounterPage(),
    );
  }
}

class StepCounterPage extends StatefulWidget {
  const StepCounterPage({super.key});

  @override
  State<StepCounterPage> createState() => _StepCounterPageState();
}

class _StepCounterPageState extends State<StepCounterPage> with WidgetsBindingObserver {
  final _stepCounter = AccurateStepCounter();
  int _steps = 0;

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    _init();
  }

  Future<void> _init() async {
    // Request permissions
    await Permission.activityRecognition.request();
    await Permission.notification.request();

    // Initialize logging for persistent storage
    await _stepCounter.initializeLogging(debugLogging: kDebugMode);

    // Start counting with terminated state sync enabled
    await _stepCounter.start(
      config: StepDetectorConfig(enableOsLevelSync: true),
    );

    // Start auto-logging to database
    await _stepCounter.startLogging(
      config: StepRecordConfig.walking(),
    );

    // Listen to real-time step count
    _stepCounter.stepEventStream.listen((event) {
      setState(() => _steps = event.stepCount);
    });

    // Handle steps from terminated state
    _stepCounter.onTerminatedStepsDetected = (steps, start, end) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('Recovered $steps steps from terminated state!')),
      );
    };
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    // CRITICAL: Track app state for proper source detection
    _stepCounter.setAppState(state);
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    _stepCounter.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Step Counter - All States')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            // Real-time step count
            Text(
              '$_steps',
              style: const TextStyle(fontSize: 72, fontWeight: FontWeight.bold),
            ),
            const Text('steps', style: TextStyle(fontSize: 24, color: Colors.grey)),
            const SizedBox(height: 40),

            // Works in foreground
            const ListTile(
              leading: Icon(Icons.phone_android, color: Colors.green),
              title: Text('Foreground'),
              subtitle: Text('Counts while app is open'),
            ),

            // Works in background
            const ListTile(
              leading: Icon(Icons.layers, color: Colors.orange),
              title: Text('Background'),
              subtitle: Text('Counts when app is minimized'),
            ),

            // Works in terminated state
            const ListTile(
              leading: Icon(Icons.power_off, color: Colors.red),
              title: Text('Terminated'),
              subtitle: Text('Recovers steps when app is killed & reopened'),
            ),
          ],
        ),
      ),
    );
  }
}

That's it! This simple example:

✅ Real-time counting - Updates UI instantly
✅ Foreground state - Counts while app is open
✅ Background state - Continues counting when minimized
✅ Terminated state - Recovers missed steps when app is killed & reopened
✅ Auto-logging - Saves all steps to database with source tracking
✅ Lifecycle tracking - setAppState() ensures proper source detection

How It Works in Each State #

State	What Happens
🟢 Foreground	Real-time updates, steps logged as `foreground`
🟡 Background	Continues counting (service on Android ≤10), steps logged as `background`
🔴 Terminated	OS tracks steps, synced on relaunch (Android 11+), logged as `terminated`

Try it: Open app → Walk 50 steps → Press home → Walk 50 more → Force kill → Walk 50 more → Reopen app → See all steps recovered! 🎉

⚙️ 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
    useForegroundServiceOnOldDevices: true,
    foregroundServiceMaxApiLevel: 29, // API level threshold (default: 29 = Android 10)
    foregroundNotificationTitle: 'Step Tracker',
    foregroundNotificationText: 'Counting your steps...',
  ),
);

Configuration Parameters #

Parameter	Default	Description
`threshold`	1.0	Movement threshold for step detection
`filterAlpha`	0.8	Low-pass filter smoothing (0.0-1.0)
`minTimeBetweenStepsMs`	200	Minimum time between steps
`enableOsLevelSync`	true	Sync with OS step counter
`useForegroundServiceOnOldDevices`	true	Use foreground service on older Android
`foregroundServiceMaxApiLevel`	29	Max API level for foreground service (29=Android 10, 31=Android 12, etc.)
`foregroundNotificationTitle`	"Step Counter"	Notification title
`foregroundNotificationText`	"Tracking your steps..."	Notification text

🔧 API Reference #