شاشة البوصلة تبدو بسيطة: اقرأ رقمًا بين 0 و 360 ثم دوّر الإبرة. الرقم هو الجزء السهل. والباقي هو المكان الذي تخطئ فيه تطبيقات البوصلة.
في الهاتف عدة حساسات (sensors) تستطيع إعطاء الاتجاه، وليست بنفس الجودة. والاتجاه يجب أن يتبع أعلى الشاشة، فيجب أن يتغير حين تدور الشاشة إلى الوضع الأفقي. والإبرة التي تُنعَّم بمتوسط عادي تدور من الطريق الطويل حين ينتقل الاتجاه من 359° إلى 1°. والحساس يُبلّغ حين يحتاج إلى معايرة (calibration)، وعلى التطبيق أن يخبر المستخدم. والـ magnetometer يشير إلى الشمال المغناطيسي لا الشمال الحقيقي.
heading_sensor إضافة (plugin) لـ Flutter تتعامل مع هذه النقاط. تقرأ حساسات rotation-vector في Android وتعطيك الاتجاه (heading) و pitch و roll، ودقة المعايرة، وتنعيمًا آمنًا حول 0°/360°، والشمال الحقيقي اختياريًا. يصفها الـ README بأنها بديل مُصان لـ flutter_compass وflutter_compass_v2. وهي لـ Android فقط.
ماذا تقدّم
أفضل حساس أولًا. تستعمل TYPE_ROTATION_VECTOR. وإن لم يكن موجودًا تستعمل TYPE_GEOMAGNETIC_ROTATION_VECTOR وهو أقل استهلاكًا للطاقة. وإن لم يوجد أي منهما تجمع الـ accelerometer والمجال المغناطيسي عبر SensorManager.getRotationMatrix. ويمكنك طلب الحساس الأقل استهلاكًا بـ preferredSource.
اتجاه و pitch و roll تتبع الشاشة. مصفوفة الدوران يُعاد إسقاطها بـ remapCoordinateSystem حسب Display.getRotation() الحالي (0° أو 90° أو 180° أو 270°)، فتتبع القيم أعلى الشاشة في الوضع العمودي والأفقي.
الدقة. كل حدث يُعلن unreliable أو low أو medium أو high، مأخوذة من onAccuracyChanged، مع علامة needsCalibration. وحين يعطي الجهاز تقديره الخاص لخطأ الاتجاه، تحصل عليه أيضًا بالدرجات.
المعدّل والتنعيم. اختر معدّل الحساس: fastest أو game أو ui أو normal أو فترة مخصّصة. وأضف low-pass filter ينتقل من 359° إلى 1° عبر 0° لا عبر 180°. والفلتر يعمل في Kotlin أو في Dart، حسب اختيارك.
الشمال الحقيقي. مرّر declinationProvider وفعّل useTrueNorth. يعرضها الـ README مع نموذج WMM2025 من الحزمة الشقيقة qibla_math.
رفيقة بالبطارية. الحساسات تُسجَّل فقط ما دام للـ stream مستمع. يُلغى تسجيلها حين يذهب التطبيق إلى الخلفية (onStop في الـ Activity) وتُسجَّل من جديد حين يعود.
القدرات. الدالة HeadingSensor.capabilities() تخبرك أي الحساسات موجودة، مثلًا أن الجهاز ليس فيه magnetometer أصلًا.
طريقة الاستعمال
أضِفها من GitHub:
dependencies:
heading_sensor:
git: https://github.com/AbdeldjalilChougui/heading_sensor
لا تحتاج أي أذونات، وminSdk هو 21.
import 'package:heading_sensor/heading_sensor.dart';
Future<void> startCompass() async {
if (!await HeadingSensor.isAvailable()) {
print('No compass on this device');
return;
}
final subscription = HeadingSensor.events(
rate: SensorRate.ui,
smoothing: const HeadingSmoothing.native(0.15),
).listen((event) {
print('${event.heading.toStringAsFixed(0)}° '
'pitch ${event.pitch.toStringAsFixed(0)}° '
'roll ${event.roll.toStringAsFixed(0)}° '
'${event.accuracy.name} via ${event.source.name}');
if (event.needsCalibration) {
print('Move the phone in a figure-8 to calibrate');
}
}, onError: (Object error) {
// HeadingSensorException('NO_SENSOR') when there is no usable sensor.
print(error);
});
// Cancel when done: this unregisters the Android sensors.
await Future<void>.delayed(const Duration(seconds: 10));
await subscription.cancel();
}
لفحص العتاد قبل عرض بوصلة أصلًا:
final caps = await HeadingSensor.capabilities();
if (!caps.hasMagnetometer) {
// No compass hardware at all.
}
print(caps.bestSource); // HeadingSource.rotationVector, or null
التنعيم
HeadingSmoothing.native(alpha) تنعّم في Kotlin، قبل أن تعبر الأحداث قناة المنصة (platform channel). وHeadingSmoothing.dart(alpha) تنعّم في Dart، ولكل مستمع فلتره الخاص. وalpha هو وزن كل عيّنة جديدة: فوق 0 بقليل يعني تنعيمًا قويًا وبطيئًا، و 1 يعني بلا تنعيم.
والفلتر متاح لوحده أيضًا:
final filter = AngleLowPassFilter(alpha: 0.5);
filter.add(359);
filter.add(1); // 0.0, not 180
السطر الأخير هو بيت القصيد. المتوسط العادي لـ 359 و 1 هو 180، أي الاتجاه المعاكس تمامًا.
الشمال الحقيقي والقبلة
الـ magnetometer يقيس الشمال المغناطيسي. للشمال الحقيقي تضيف الانحراف المغناطيسي (declination) في موقع المستخدم. الحزمة qibla_math فيها نموذج NOAA المغناطيسي العالمي (WMM2025) واتجاه القبلة. وبما أن هذه الإضافة تقوم بتعويض الميل (tilt compensation) في الجانب الـ native، فأنت تحتاج منها فقط الانحراف وحسابات القبلة:
Stream<double> qiblaNeedle(double latitude, double longitude) {
// The provider runs once per event, so compute the declination once.
final declination = WorldMagneticModel.wmm2025
.calculate(
latitude: latitude,
longitude: longitude,
decimalYear: decimalYear(DateTime.now()),
)
.declination;
final qibla = qiblaBearing(latitude, longitude);
return HeadingSensor.events(
smoothing: const HeadingSmoothing.native(0.15),
useTrueNorth: true,
declinationProvider: (_) => declination,
).map((e) => qiblaNeedleAngle(trueHeading: e.heading, qiblaBearing: qibla));
}
الحزمتان تصدّران normalizeDegrees وsignedAngleDifference، ولذلك يخفيهما الـ README عند استيراد qibla_math. وإن أرجع الـ provider القيمة null يكون isTrueNorth خاطئًا وheading هو الاتجاه المغناطيسي. والتنعيم يُطبَّق على الاتجاه المغناطيسي قبل إضافة الانحراف.
المعايرة
حين يكون needsCalibration صحيحًا، اطلب من المستخدم أن يمسك الهاتف ويرسم شكل 8 في الهواء عدة مرات، مع تدوير الهاتف في كل الاتجاهات، بعيدًا عن المعادن والمغناطيس والحواسيب المحمولة وأغطية الهواتف المغناطيسية. يحدّث Android الدقة، وتصلك القيمة الجديدة في الحدث التالي.
الانتقال من flutter_compass
-
FlutterCompass.events(القابلة لـ null) تصبحHeadingSensor.events(). افحصHeadingSensor.isAvailable()أولًا. -
CompassEvent.headingتصبحHeadingEvent.heading، وهو مغناطيسي ما لم تفعّلuseTrueNorth. -
CompassEvent.accuracyتصبح الـ enumHeadingEvent.accuracy، معheadingAccuracyDegreesحين يوفّرها الجهاز. - بدل
headingForCameraModeاستعملpitchوroll. - الاتجاه
nullعند غياب الحساس يصبح خطأ في الـ stream:HeadingSensorException('NO_SENSOR').
أشياء يجب معرفتها
- Android فقط. iOS غير مدعوم. ويشير الـ README هناك إلى heading في CLLocationManager.
- لم تُختبر بعد على هاتف حقيقي. الحسابات الخالصة (azimuth، جدول إعادة الإسقاط، التنعيم، اختيار الحساس) لها اختبارات وحدة على JVM، وواجهة Dart لها اختبارات على قناة وهمية (mocked channel). واختبار تكامل على المحاكي يضبط الـ accelerometer والـ magnetometer الافتراضيين عبر adb console ويفحص الاتجاه و pitch وتسجيل الحساسات والتوقف في الخلفية. تم تشغيله على محاكي Android بصورة نظام Pixel 10، API 37.
- المسار البديل فقط هو الذي قورن بمجالات معروفة. على المحاكي تُرسل مصادر rotation-vector أحداثًا، لكن adb console لا يستطيع ضبطها مباشرة. فاتجاه accelerometer + magnetometer فقط هو الذي قورن بقيم معروفة.
-
إعداد native واحد في كل مرة. إن استمعت إلى stream ثانٍ من
HeadingSensor.events(...)بخيارات أخرى فإنه يحل محل الأول. لاستعمال نفس القراءة في عدة widgets استمع إلى نفس الـ stream. - الاتجاه فقط هو الذي يُنعَّم. pitch و roll يمرّان كما هما.
- المسار البديل أكثر ضجيجًا. مع accelerometer + magnetometer يستعمل الاتجاه الـ accelerometer الخام كجاذبية، فيكون أكثر ضجيجًا أثناء الحركة من حساسات rotation-vector.
- الطوابع الزمنية تفترض ساعة elapsed-realtime كما يوثّق Android. بعض الأجهزة القديمة استعملت ساعة أخرى.
- المحركات التي بلا Activity تواصل القراءة ما دام هناك مستمع. التوقف يحدث حين تتوقف Activity.
- البوصلة تقرأ المجال المغناطيسي المحلي. الفولاذ والمغناطيس والإلكترونيات القريبة تحرفه، ولا يستطيع أي حساس أو نموذج تصحيح ذلك.
لماذا بنيتها
الاتجاه ليس رقمًا واحدًا. يأتي من حساس محدد، بدقة معلنة، بالنسبة لدوران الشاشة الحالي، وبالنسبة للشمال المغناطيسي أو الحقيقي. مع flutter_compass الـ stream نفسه قابل لـ null، وغياب الحساس يظهر كاتجاه null، وجدول الانتقال في الـ README يذكر أن قيمة الدقة فيه بالدرجات وخاصة بـ iOS.
أردت حدثًا يحمل كل ذلك: المصدر الذي أنتجه، الدقة وعلامة المعايرة، pitch و roll، وهل هو شمال حقيقي. وأردت أن تكون الأجزاء التي تحتاجها كل شاشة بوصلة داخل الإضافة ومختبرة: إعادة الإسقاط حسب دوران الشاشة، الفلتر الذي يحترم الالتفاف حول 360°، وإيقاف الحساسات حين لا يستمع أحد أو حين يكون التطبيق في الخلفية.
احصل على الكود
المصدر، والـ README، وتطبيق المثال واختبار التكامل على المحاكي، كلها على GitHub: https://github.com/AbdeldjalilChougui/heading_sensor. الرخصة MIT. ومرحبًا بالـ issues والـ pull requests، خصوصًا القراءات من هواتف حقيقية.
نُشر في الأصل على abdeldjalilchougui.biz.
