Overview

MagnetoSense is an OutSystems 11 mobile plugin that provides access to the device's built-in magnetometer sensor.

A magnetometer measures the surrounding magnetic field along the device's X, Y, and Z axes. MagnetoSense exposes these readings to OutSystems applications and also provides the calculated magnetic field magnitude in microteslas (µT).

The component supports both single readings and continuous monitoring, making it suitable for applications that need to react to changes in the surrounding magnetic field.

The underlying Cordova plugin provides single-reading and continuous-listening APIs and exposes raw X, Y, Z values together with a calculated magnitude.

Features

• Detect whether a magnetometer is available on the device.
• Retrieve a single magnetic field reading.
• Retrieve X, Y, and Z magnetic field values.
• Retrieve magnetic field magnitude in µT.
• Start continuous magnetometer monitoring.
• Retrieve the latest reading while monitoring.
• Stop continuous monitoring.
• Includes an interactive demo application for testing the sensor on a physical device.

Requirements

• OutSystems 11
• Mobile application
• A physical device with a magnetometer sensor

Not every Android device contains every type of sensor, so applications should check sensor availability at runtime before depending on magnetometer functionality. Android specifically exposes the geomagnetic field sensor as TYPE_MAGNETIC_FIELD.

Important: Sensor availability and measurement behavior depend on the physical device hardware.

Client Actions

1. CheckMagnetometerAvailability

Checks whether the device has an accessible magnetometer sensor.

Outputs

Example

CheckMagnetometerAvailability
        ↓
If IsAvailable
        ↓
Continue using magnetometer

If the sensor is unavailable, your application should gracefully disable or hide magnetometer-dependent functionality.

2. GetCurrentReading

Retrieves one reading from the magnetometer.

Outputs

The Android magnetic-field sensor reports magnetic field strength for all three physical axes in µT.

3. StartWatch

Starts continuous magnetometer monitoring.

Once monitoring is started, new readings are received continuously while the watch is active.

The underlying plugin's watchReadings API repeatedly invokes its success callback with the latest X, Y, Z, and magnitude values.

Outputs

4. GetLatestReading

Returns the most recently captured magnetometer reading while monitoring is active.

Outputs

5. StopWatch

Stops the active magnetometer monitoring process.

Call this action when continuous monitoring is no longer required.

For example:

StartWatch
    ↓
Use magnetometer readings
    ↓
StopWatch

Stopping monitoring when it is no longer needed is recommended because continuously registered sensors can consume device resources and battery. Android documentation specifically recommends unregistering sensor listeners when they are no longer needed.

Understanding the Readings

MagnetoSense provides three directional measurements:

X → Magnetic field along X axis
Y → Magnetic field along Y axis
Z → Magnetic field along Z axis

All three values are expressed in microteslas (µT).

The Magnitude value represents the overall magnetic field strength and is calculated from the three axis values.

Conceptually:

Magnitude = √(X² + Y² + Z²)

The magnitude is always represented as a positive value by the underlying plugin.

Single Reading Example

A simple implementation can retrieve one reading when the user presses a button:

Button
   ↓
CheckMagnetometerAvailability
   ↓
If IsAvailable
   ↓
GetCurrentReading
   ↓
Display X / Y / Z / Magnitude

For example, your UI could display:

Magnetic Field

X       24.32 µT
Y      -46.54 µT
Z       36.32 µT

Magnitude
63.51 µT

Continuous Monitoring Example

For applications that need real-time changes:

CheckMagnetometerAvailability
          ↓
       StartWatch
          ↓
  Continuous readings
          ↓
   Update application UI
          ↓
       StopWatch

This can be used to display a live magnetic-field meter, detect sudden changes, or trigger application behavior when the magnetic field crosses a defined threshold.

Real-World Use Cases

1. Digital Compass

A magnetometer can be combined with an accelerometer to determine the device's orientation relative to magnetic north.

This can be used for:

• Compass applications
• Navigation interfaces
• Direction indicators
• Outdoor applications

Android documentation describes using the geomagnetic field sensor together with the accelerometer to determine device orientation relative to magnetic north.

2. Magnetic Object Detection

Magnetic objects can cause significant changes in the magnetic field measured by the device.

For example, an application could monitor:

Normal field
     ↓
Magnetic field changes
     ↓
Threshold exceeded
     ↓
Trigger application event

Potential applications include experimental magnetic-object detection and educational/science applications.

The underlying plugin itself describes magnetic-field detection and science-toolkit applications as potential use cases.

3. Magnetic Door or Window Detection

A magnetometer can potentially be used to detect changes caused by a nearby magnet.

For example:

Door closed
   ↓
Magnetic field = normal
   ↓
Door opens
   ↓
Magnetic field changes
   ↓
Application detects the change

This could be useful for prototypes involving:

• Door monitoring
• Cabinet monitoring
• Equipment access detection
• Experimental IoT-style solutions

Actual reliability depends heavily on the device position, magnet placement, distance, and surrounding magnetic interference.

4. Magnetic Interference Detection

Applications can monitor magnetic-field changes around equipment or environments.

For example, a mobile application could record magnetic-field readings while a device is moved around an area and identify locations where magnetic interference increases significantly.

This can be useful for:

• Field diagnostics
• Equipment testing
• Educational demonstrations
• Environmental experiments

5. Metal/Magnetic Material Experiments

Magnetic materials can affect the readings reported by the magnetometer.

A developer can continuously monitor Magnitude and detect significant deviations from a baseline value.

For example:

Baseline = 60 µT

Current = 62 µT
→ Normal

Current = 180 µT
→ Significant change

Current = 900 µT
→ Strong magnetic disturbance

This can be used to build experimental magnetic-field or metal-detection applications.

Note: MagnetoSense provides sensor measurements; it does not classify objects as a specific material or provide guaranteed metal detection.

6. Educational and Science Applications

MagnetoSense can be useful for applications that demonstrate concepts such as:

• Earth's magnetic field
• Magnetic-field strength
• Three-dimensional magnetic-field measurements
• Magnetic interference
• Effects of magnets at different distances

The live monitoring capability makes it particularly suitable for interactive demonstrations.

Demo Application

MagnetoSense includes a dedicated interactive demo application.

The demo provides:

• Magnetometer availability status
• Live magnetic-field magnitude
• X-axis reading
• Y-axis reading
• Z-axis reading
• Monitoring status
• Start Monitoring control
• Stop Monitoring control

The demo is designed to make it easy to test the plugin on a physical mobile device.

Suggested test

1. Install and run the demo on a physical device.
2. Confirm that Magnetometer Available is displayed.
3. Start monitoring.
4. Observe the X, Y, Z, and magnitude values.
5. Move a magnet close to the device.
6. Observe the change in the magnetic-field readings.
7. Move the magnet away and observe the readings return toward their previous range.
8. Press Stop Monitoring when finished.

This also provides a practical reference for developers integrating MagnetoSense into their own OutSystems applications.

Sensor Availability

A magnetometer is a hardware sensor and is not guaranteed to exist on every mobile device.

Therefore, applications should always call:

CheckMagnetometerAvailability

before depending on magnetometer functionality.

Android explicitly notes that manufacturers are not required to include every sensor type on every device.

Sensor Accuracy and Calibration

Magnetic-field readings can be affected by:

• Device orientation
• Nearby magnets
• Metal objects
• Electronic equipment
• Magnetic interference
• Device-specific calibration

For testing, Android recommends moving the device in a figure-eight pattern to improve magnetometer accuracy.

The values should therefore be treated as sensor measurements rather than universally fixed environmental values.

Performance Considerations

Continuous monitoring should only be enabled when required.

For example:

Screen opens
    ↓
Check availability
    ↓
User starts monitoring
    ↓
StartWatch
    ↓
User finishes
    ↓
StopWatch

Avoid keeping the sensor active unnecessarily, especially in screens where the readings are not being used.

Third-Party Dependency

MagnetoSense uses the open-source cordova-plugin-magnetometer, originally developed by Rameez Raja and Steven de Salas, under the MIT License. The plugin provides the underlying magnetometer APIs for retrieving individual readings and continuously monitoring sensor changes.

Cordova-plugin-magnetometer repository

MagnetoSense's own component code is distributed under the license specified by the component.

Important Notes

• Magnetometer functionality requires a physical device containing a compatible sensor.
• Sensor readings vary between devices.
• Magnetic objects and surrounding electronics can significantly affect readings.
• The X, Y, and Z values are directional measurements and can change as the device orientation changes.
• Always stop continuous monitoring when it is no longer required.
• The component exposes sensor data; application-specific interpretation, thresholds, filtering, and business logic should be implemented by the consuming application.

Quick Reference