Throw exception when compass not found in iOS

README.md

@@ -63,21 +63,22 @@ Add code to request permissions.
 if (Platform.isAndroid) await Permission.location.request();
 ```
 
-## Precautions
-
-**CompassX `heading` currently supports only portrait mode. It is recommended to fix the orientation of the device.**
+CompassX `heading` currently supports only portrait mode. It is recommended to fix the orientation of the device.
 ```dart
 SystemChrome.setPreferredOrientations([
         DeviceOrientation.portraitUp,
         DeviceOrientation.portraitDown,
       ]);
 ```
 
+## Testing
+
+**It is recommended to use a real device.** iOS simulators cannot use the heading sensor (compass). See [Testing CompassX](https://github.com/natsuk4ze/compassx/wiki#checking-the-accuracy-of-compassx) for details.
+
+
 ## Documentation
 
-**If you are going to use this plugin in your product apps, I strongly suggest you read [full documentation](https://github.com/natsuk4ze/compassx/wiki) carefully**.  
-When testing, use the actual device for testing. The emulator may not provide correct sensor data.  
+If you are going to use this plugin in your product apps, I strongly suggest you read [full documentation](https://github.com/natsuk4ze/compassx/wiki) carefully.
 
-- [Testing CompassX](https://github.com/natsuk4ze/compassx/wiki#checking-the-accuracy-of-compassx)
 - [True Heading vs Magnetic Heading](https://github.com/natsuk4ze/compassx/wiki#true-heading)
 - [How to calibrate your device's compass](https://github.com/natsuk4ze/compassx/wiki#calibration)

example/lib/main.dart

@@ -29,7 +29,8 @@ class App extends StatelessWidget {
             child: StreamBuilder<CompassXEvent>(
               stream: CompassX.events,
               builder: (context, snapshot) {
-                if (!snapshot.hasData) return const Text('No data');
+                if (snapshot.hasError) return Text(snapshot.error.toString());
+                if (!snapshot.hasData) return const CircularProgressIndicator();
                 final compass = snapshot.data!;
                 return Column(
                   mainAxisSize: MainAxisSize.min,

ios/Classes/CompassxPlugin.swift

@@ -22,6 +22,11 @@ public class CompassXPlugin: NSObject, FlutterPlugin, FlutterStreamHandler, CLLo
 
     public func onListen(withArguments _: Any?, eventSink events: @escaping FlutterEventSink) -> FlutterError? {
         eventSink = events
+        let isHeadingAvailable = CLLocationManager.headingAvailable()
+        if !isHeadingAvailable {
+            eventSink?(FlutterError(code: "SENSOR_NOT_FOUND", message: "No compass sensor found.", details: nil))
+            return nil
+        }
         locationManager.startUpdatingHeading()
         return nil
     }

lib/src/compassx.dart

@@ -11,7 +11,9 @@ final class CompassX {
 
   /// [CompassXEvent] stream for using the compass sensor.
   ///
-  /// Throws [CompassXException] for older or excessively cheap Android devices 
-  /// that do not have a compass sensor.
+  /// Throw [CompassXException] when the compass sensor is not available. 
+  /// That includes the following cases.
+  /// - Older or excessively cheap Android devices.
+  /// - iOS simulators.
   static Stream<CompassXEvent> get events => CompassXPlatform.events;
 }

lib/src/compassx_event.dart

@@ -38,6 +38,9 @@ final class CompassXEvent {
   /// If this value is true, the sensor values are unreliable and should.
   /// See the [wiki](https://github.com/natsuk4ze/compassx/wiki) for
   /// calibration instructions.
+  /// Note that this is not always possible to detect. For use cases where 
+  /// discretion is required, it is recommended to use [accuracy] to set your 
+  /// own adjustment lines or to prompt for calibration each time.
   final bool shouldCalibrate;
 
   /// Factory for the map data obtained from the stream of [EventChannel].