Magnetic Field Sensor (#1731)

Add Kodular implementation of a Magnetic Field Sensor, which can be used to detect changes
in the magnetic field around the phone. It is useful, for example, to interact with magnetic
buttons and trigger actions.

appinventor/appengine/src/com/google/appinventor/client/Images.java

@@ -653,6 +653,12 @@ public interface Images extends Resources {
    */
   @Source("com/google/appinventor/images/mediaIcon_video.png")
   ImageResource mediaIconVideo();
+  
+  /**
+   * Designer palette item: Magnetic Field Sensor component
+   */
+  @Source("com/google/appinventor/images/magneticSensor.png")
+  ImageResource magneticSensor();
 
   /**
    * Designer palette item:

appinventor/appengine/src/com/google/appinventor/client/OdeMessages.java

@@ -5215,4 +5215,41 @@ public interface OdeMessages extends Messages, AutogeneratedOdeMessages {
   @DefaultMessage("Wheelchair")
   @Description("The label used to indicate wheelchair navigation.")
   String WheelchairNavMethod();
+
+  // Magnetic Field Sensor Componet
+  @DefaultMessage("XStrength")
+  @Description("")
+  String XstrengthProperties();
+
+  @DefaultMessage("YStrength")
+  @Description("")
+  String YstrengthProperties();
+
+  @DefaultMessage("ZStrength")
+  @Description("")
+  String ZstrengthProperties();
+
+  @DefaultMessage("MagneticChanged")
+  @Description("")
+  String MagneticChangedEvents();
+
+  @DefaultMessage("xStrength")
+  @Description("")
+  String xStrengthParams();
+
+  @DefaultMessage("yStrength")
+  @Description("")
+  String yStrengthParams();
+
+  @DefaultMessage("zStrength")
+  @Description("")
+  String zStrengthParams();
+
+  @DefaultMessage("absoluteStrength")
+  @Description("")
+  String absoluteStrengthParams();
+
+  @DefaultMessage("AbsoluteStrength")
+  @Description("")
+  String AbsoluteStrengthProperties();
 }

appinventor/appengine/src/com/google/appinventor/client/editor/simple/palette/SimpleComponentDescriptor.java

@@ -170,6 +170,7 @@ public final class SimpleComponentDescriptor {
     bundledImages.put("images/featurecollection.png", images.featurecollection());
     bundledImages.put("images/navigation.png", images.navigationComponent());
     bundledImages.put("images/arduino.png", images.arduino());
+    bundledImages.put("images/magneticSensor.png", images.magneticSensor());
 
     imagesInitialized = true;
   }

appinventor/components/src/com/google/appinventor/components/common/YaVersion.java

@@ -1335,6 +1335,9 @@ public class YaVersion {
   //For SERIAL_COMPONENT_VERSION: Initial Version
   public static final int SERIAL_COMPONENT_VERSION = 1;
 
+  //For MAGNETICFIELDSENSOR_COMPONENT_VERSION: Initial Version
+  public static final int MAGNETICFIELDSENSOR_COMPONENT_VERSION = 1;
+
   // Rendezvous Server Location
   public static final String RENDEZVOUS_SERVER = "rendezvous.appinventor.mit.edu";
 

appinventor/components/src/com/google/appinventor/components/runtime/MagneticFieldSensor.java

+// -*- mode: java; c-basic-offset: 2; -*-
+// Copyright 2016-2019 MIT, All rights reserved
+// Copyright 2017-2019 Kodular, All rights reserved
+// Released under the Apache License, Version 2.0
+// http://www.apache.org/licenses/LICENSE-2.0
+
+package com.google.appinventor.components.runtime;
+
+import android.hardware.Sensor;
+import android.hardware.SensorEvent;
+import android.hardware.SensorEventListener;
+import android.hardware.SensorManager;
+
+import com.google.appinventor.components.annotations.DesignerComponent;
+import com.google.appinventor.components.annotations.DesignerProperty;
+import com.google.appinventor.components.annotations.PropertyCategory;
+import com.google.appinventor.components.annotations.SimpleEvent;
+import com.google.appinventor.components.annotations.SimpleObject;
+import com.google.appinventor.components.annotations.SimpleProperty;
+import com.google.appinventor.components.common.ComponentCategory;
+import com.google.appinventor.components.common.YaVersion;
+
+
+@DesignerComponent(
+    category = ComponentCategory.SENSORS,
+    description = "<p>Non-visible component that measures the ambient geomagnetic field for all three physical axes " +
+        "(x, y, z) in Tesla https://en.wikipedia.org/wiki/Tesla_(unit).</p>",
+    iconName = "images/magneticSensor.png",
+    nonVisible = true,
+    version = YaVersion.MAGNETICFIELDSENSOR_COMPONENT_VERSION)
+@SimpleObject
+
+public class MagneticFieldSensor extends AndroidNonvisibleComponent implements SensorEventListener, Deleteable, OnPauseListener, OnResumeListener, OnStopListener, SensorComponent {
+  private double absoluteStrength;
+  private boolean enabled = true;
+  private boolean listening;
+  private Sensor magneticSensor;
+  private final SensorManager sensorManager;
+  private float xStrength;
+  private float yStrength;
+  private float zStrength;
+
+  public MagneticFieldSensor(ComponentContainer container) {
+    super(container.$form());
+    form.registerForOnResume(this);
+    form.registerForOnStop(this);
+    form.registerForOnPause(this);
+    sensorManager = (SensorManager) container.$context().getSystemService("sensor");
+    magneticSensor = sensorManager.getDefaultSensor(2);
+    startListening();
+  }
+
+  @SimpleProperty(category = PropertyCategory.BEHAVIOR, description = "Indicates that there is a magnetic field " +
+      "sensor in the device and it is available.")
+  public boolean Available() {
+    return sensorManager.getSensorList(2).size() > 0;
+  }
+
+  @SimpleProperty(category = PropertyCategory.BEHAVIOR, description = "Indicates the maximum range the magnetic " +
+      "sensor can reach.")
+  public float MaximumRange() {
+    return magneticSensor.getMaximumRange();
+  }
+
+  @SimpleProperty(category = PropertyCategory.BEHAVIOR, description = "Indicates whether or not the magnetic field " +
+      "sensor is enabled and working.")
+  public boolean Enabled() {
+    return enabled;
+  }
+
+  @DesignerProperty(defaultValue = "True", editorType = "boolean")
+  @SimpleProperty
+  public void Enabled(boolean localEnabled) {
+    if (enabled != localEnabled) {
+      enabled = localEnabled;
+    }
+    if (enabled) {
+      startListening();
+    } else {
+      stopListening();
+    }
+  }
+
+  @SimpleEvent(description = "Triggers when magnetic field has changed, setting the new values in parameters.")
+  public void MagneticChanged(float xStrength, float yStrength, float zStrength, double absoluteStrength) {
+    EventDispatcher.dispatchEvent(this, "MagneticChanged", xStrength, yStrength, zStrength, absoluteStrength);
+  }
+
+  @SimpleProperty(category = PropertyCategory.BEHAVIOR, description = "Indicates the absolute strength of the field.")
+  public double AbsoluteStrength() {
+    return absoluteStrength;
+  }
+
+  @SimpleProperty(category = PropertyCategory.BEHAVIOR, description = "Indicates the field's strength in the X-axis.")
+  public float XStrength() {
+    return xStrength;
+  }
+
+  @SimpleProperty(category = PropertyCategory.BEHAVIOR, description = "Indicates the field's strength in the Y-axis.")
+  public float YStrength() {
+    return yStrength;
+  }
+
+  @SimpleProperty(category = PropertyCategory.BEHAVIOR, description = "Indicates the field's strength in the Z-axis.")
+  public float ZStrength() {
+    return zStrength;
+  }
+
+  private Sensor getMagneticSensor() {
+    Sensor sensor = sensorManager.getDefaultSensor(2);
+    return sensor != null ? sensor : sensorManager.getDefaultSensor(2);
+  }
+
+  public void onResume() {
+    if (enabled) {
+      startListening();
+    }
+  }
+
+  public void onStop() {
+    if (enabled) {
+      stopListening();
+    }
+  }
+
+  public void onDelete() {
+    if (enabled) {
+      stopListening();
+    }
+  }
+
+  public void onPause() {
+    stopListening();
+  }
+
+  private void startListening() {
+    if (!listening && sensorManager != null && magneticSensor != null) {
+      sensorManager.registerListener(this, magneticSensor, 3);
+      listening = true;
+    }
+  }
+
+  private void stopListening() {
+    if (listening && sensorManager != null) {
+      sensorManager.unregisterListener(this);
+      listening = false;
+      xStrength = 0.0f;
+      yStrength = 0.0f;
+      zStrength = 0.0f;
+    }
+  }
+
+  public void onSensorChanged(SensorEvent sensorEvent) {
+    if (enabled && sensorEvent.sensor.getType() == 2) {
+      float[] values = (float[]) sensorEvent.values.clone();
+      xStrength = sensorEvent.values[0];
+      yStrength = sensorEvent.values[1];
+      zStrength = sensorEvent.values[2];
+      absoluteStrength = Math.sqrt((double) (((xStrength * xStrength) + (yStrength * yStrength)) + (zStrength * zStrength)));
+      MagneticChanged(xStrength, yStrength, zStrength, absoluteStrength);
+    }
+  }
+
+  public void onAccuracyChanged(Sensor sensor, int i) {
+  }
+}

appinventor/docs/html/reference/components/connectivity.html

@@ -474,34 +474,40 @@ set the following properties:
 
 <h2 id="Serial">Serial</h2>
 
+<p>Component for Serial</p>
+
 <h3 id="Serial-Properties">Properties</h3>
 
 <dl class="properties">
-    <dt id="Serial.BaudRate" class="number do"><em>BaudRate</em></dt>
-    <dd>Specifies the baud rate for the connection.</dd>
-    <dt id="Serial.BufferSize" class="number do"><em>BufferSize</em></dt>
-    <dd>Specifies the buffer size in bytes for the connection.</dd>
-    <dt id="Serial.IsInitialized" class="boolean bo"><em>IsInitialized</em></dt>
-    <dd>Returns true when the component has been initialized.</dd>
-    <dt id="Serial.IsOpen" class="boolean bo"><em>IsOpen</em></dt>
-    <dd>Returns true when the connection has been opened.</dd>
+  <dt id="Serial.BaudRate" class="number"><em>BaudRate</em></dt>
+  <dd>Property for BaudRate</dd>
+  <dt id="Serial.BufferSize" class="number"><em>BufferSize</em></dt>
+  <dd>Property for BufferSize</dd>
+  <dt id="Serial.IsInitialized" class="boolean ro bo"><em>IsInitialized</em></dt>
+  <dd>Returns true when the Serial has been initialized.</dd>
+  <dt id="Serial.IsOpen" class="boolean ro bo"><em>IsOpen</em></dt>
+  <dd>Returns true when the Serial connection is open.</dd>
 </dl>
 
+<h3 id="Serial-Events">Events</h3>
+
+<p class="events">None</p>
+
 <h3 id="Serial-Methods">Methods</h3>
 
 <dl class="methods">
-    <dt id="Serial.CloseSerial" class="method returns boolean"><i></i> CloseSerial()</dt>
-    <dd>Attempts to close the serial connection, returning true when success.</dd>
-    <dt id="Serial.InitializeSerial" class="method"><i></i> InitializeSerial()</dt>
-    <dd>Initializes the serial component to be ready to use.</dd>
-    <dt id="Serial.OpenSerial" class="method returns boolean"><i></i> OpenSerial()</dt>
-    <dd>Attempts to close the serial connection, returning true when success.</dd>
-    <dt id="Serial.PrintSerial" class="method"><i></i> PrintSerial(<em class="text">data</em>)</dt>
-    <dd>Sends the given data to the serial connection, and appends a new line.</dd>
-    <dt id="Serial.ReadSerial" class="method"><i></i> ReadSerial()</dt>
-    <dd>Starts reading the serial port. Will raise AfterReadSerial event.</dd>
-    <dt id="Serial.WriteSerial" class="method"><i></i> WriteSerial(<em class="text">data</em>)</dt>
-    <dd>Sends the given data to the serial connection.</dd>
+  <dt id="Serial.CloseSerial" class="method returns boolean"><i></i> CloseSerial()</dt>
+  <dd>Closes serial connection. Returns true when closed.</dd>
+  <dt id="Serial.InitializeSerial" class="method"><i></i> InitializeSerial()</dt>
+  <dd>Initializes serial connection.</dd>
+  <dt id="Serial.OpenSerial" class="method returns boolean"><i></i> OpenSerial()</dt>
+  <dd>Opens serial connection. Returns true when opened.</dd>
+  <dt id="Serial.PrintSerial" class="method"><i></i> PrintSerial(<em class="text">data</em>)</dt>
+  <dd>Writes given data to serial, and appends a new line at the end.</dd>
+  <dt id="Serial.ReadSerial" class="method returns text"><i></i> ReadSerial()</dt>
+  <dd>Reads data from serial.</dd>
+  <dt id="Serial.WriteSerial" class="method"><i></i> WriteSerial(<em class="text">data</em>)</dt>
+  <dd>Writes given data to serial.</dd>
 </dl>
 
 <h2 id="Web">Web</h2>

appinventor/docs/html/reference/components/sensors.html

@@ -139,6 +139,7 @@
   <li><a href="#Hygrometer">Hygrometer</a></li>
   <li><a href="#LightSensor">LightSensor</a></li>
   <li><a href="#LocationSensor">LocationSensor</a></li>
+  <li><a href="#MagneticFieldSensor">MagneticFieldSensor</a></li>
   <li><a href="#NearField">NearField</a></li>
   <li><a href="#OrientationSensor">OrientationSensor</a></li>
   <li><a href="#Pedometer">Pedometer</a></li>
@@ -629,6 +630,40 @@ Valid values for the month field are 1-12 and 1-31 for the day field.</dd>
   <dd>Derives longitude from the given <code class="highlighter-rouge">locationName</code>.</dd>
 </dl>
 
+<h2 id="MagneticFieldSensor">MagneticFieldSensor</h2>
+
+<p>Component for MagneticFieldSensor</p>
+
+<h3 id="MagneticFieldSensor-Properties">Properties</h3>
+
+<dl class="properties">
+  <dt id="MagneticFieldSensor.AbsoluteStrength" class="number ro bo"><em>AbsoluteStrength</em></dt>
+  <dd>Indicates the absolute strength of the field.</dd>
+  <dt id="MagneticFieldSensor.Available" class="boolean ro bo"><em>Available</em></dt>
+  <dd>Indicates that there is a magnetic field sensor in the device and it is available.</dd>
+  <dt id="MagneticFieldSensor.Enabled" class="boolean"><em>Enabled</em></dt>
+  <dd>Property for Enabled</dd>
+  <dt id="MagneticFieldSensor.MaximumRange" class="number ro bo"><em>MaximumRange</em></dt>
+  <dd>Indicates the maximum range the magnetic sensor can reach.</dd>
+  <dt id="MagneticFieldSensor.XStrength" class="number ro bo"><em>XStrength</em></dt>
+  <dd>Indicates the field’s strength in the X-axis.</dd>
+  <dt id="MagneticFieldSensor.YStrength" class="number ro bo"><em>YStrength</em></dt>
+  <dd>Indicates the field’s strength in the Y-axis.</dd>
+  <dt id="MagneticFieldSensor.ZStrength" class="number ro bo"><em>ZStrength</em></dt>
+  <dd>Indicates the field’s strength in the Z-axis.</dd>
+</dl>
+
+<h3 id="MagneticFieldSensor-Events">Events</h3>
+
+<dl class="events">
+  <dt id="MagneticFieldSensor.MagneticChanged">MagneticChanged(<em class="number">xStrength</em>,<em class="number">yStrength</em>,<em class="number">zStrength</em>,<em class="number">absoluteStrength</em>)</dt>
+  <dd>Triggers when magnetic field has changed, setting the new values in parameters.</dd>
+</dl>
+
+<h3 id="MagneticFieldSensor-Methods">Methods</h3>
+
+<p class="methods">None</p>
+
 <h2 id="NearField">NearField</h2>
 
 <p>Non-visible component to provide NFC capabilities. For now this component supports the reading

appinventor/docs/markdown/reference/components/connectivity.md

@@ -11,6 +11,7 @@ Table of Contents:
 * [ActivityStarter](#ActivityStarter)
 * [BluetoothClient](#BluetoothClient)
 * [BluetoothServer](#BluetoothServer)
+* [Serial](#Serial)
 * [Web](#Web)
 
 ## ActivityStarter  {#ActivityStarter}
@@ -391,6 +392,56 @@ Use the `BluetoothServer` component to turn your device into a server that recei
 {:id="BluetoothServer.StopAccepting" class="method"} <i/> StopAccepting()
 : Stop accepting an incoming connection.
 
+## Serial  {#Serial}
+
+Component for Serial
+
+
+
+### Properties  {#Serial-Properties}
+
+{:.properties}
+
+{:id="Serial.BaudRate" .number} *BaudRate*
+: Property for BaudRate
+
+{:id="Serial.BufferSize" .number} *BufferSize*
+: Property for BufferSize
+
+{:id="Serial.IsInitialized" .boolean .ro .bo} *IsInitialized*
+: Returns true when the Serial has been initialized.
+
+{:id="Serial.IsOpen" .boolean .ro .bo} *IsOpen*
+: Returns true when the Serial connection is open.
+
+### Events  {#Serial-Events}
+
+{:.events}
+None
+
+
+### Methods  {#Serial-Methods}
+
+{:.methods}
+
+{:id="Serial.CloseSerial" class="method returns boolean"} <i/> CloseSerial()
+: Closes serial connection. Returns true when closed.
+
+{:id="Serial.InitializeSerial" class="method"} <i/> InitializeSerial()
+: Initializes serial connection.
+
+{:id="Serial.OpenSerial" class="method returns boolean"} <i/> OpenSerial()
+: Opens serial connection. Returns true when opened.
+
+{:id="Serial.PrintSerial" class="method"} <i/> PrintSerial(*data*{:.text})
+: Writes given data to serial, and appends a new line at the end.
+
+{:id="Serial.ReadSerial" class="method returns text"} <i/> ReadSerial()
+: Reads data from serial.
+
+{:id="Serial.WriteSerial" class="method"} <i/> WriteSerial(*data*{:.text})
+: Writes given data to serial.
+
 ## Web  {#Web}
 
 Non-visible component that provides functions for HTTP GET, POST, PUT, and DELETE requests.

appinventor/docs/markdown/reference/components/sensors.md

@@ -16,6 +16,7 @@ Table of Contents:
 * [Hygrometer](#Hygrometer)
 * [LightSensor](#LightSensor)
 * [LocationSensor](#LocationSensor)
+* [MagneticFieldSensor](#MagneticFieldSensor)
 * [NearField](#NearField)
 * [OrientationSensor](#OrientationSensor)
 * [Pedometer](#Pedometer)
@@ -593,6 +594,50 @@ Non-visible component providing location information, including [`Latitude`](#Lo
 {:id="LocationSensor.LongitudeFromAddress" class="method returns number"} <i/> LongitudeFromAddress(*locationName*{:.text})
 : Derives longitude from the given `locationName`.
 
+## MagneticFieldSensor  {#MagneticFieldSensor}
+
+Component for MagneticFieldSensor
+
+
+
+### Properties  {#MagneticFieldSensor-Properties}
+
+{:.properties}
+
+{:id="MagneticFieldSensor.AbsoluteStrength" .number .ro .bo} *AbsoluteStrength*
+: Indicates the absolute strength of the field.
+
+{:id="MagneticFieldSensor.Available" .boolean .ro .bo} *Available*
+: Indicates that there is a magnetic field sensor in the device and it is available.
+
+{:id="MagneticFieldSensor.Enabled" .boolean} *Enabled*
+: Property for Enabled
+
+{:id="MagneticFieldSensor.MaximumRange" .number .ro .bo} *MaximumRange*
+: Indicates the maximum range the magnetic sensor can reach.
+
+{:id="MagneticFieldSensor.XStrength" .number .ro .bo} *XStrength*
+: Indicates the field's strength in the X-axis.
+
+{:id="MagneticFieldSensor.YStrength" .number .ro .bo} *YStrength*
+: Indicates the field's strength in the Y-axis.
+
+{:id="MagneticFieldSensor.ZStrength" .number .ro .bo} *ZStrength*
+: Indicates the field's strength in the Z-axis.
+
+### Events  {#MagneticFieldSensor-Events}
+
+{:.events}
+
+{:id="MagneticFieldSensor.MagneticChanged"} MagneticChanged(*xStrength*{:.number},*yStrength*{:.number},*zStrength*{:.number},*absoluteStrength*{:.number})
+: Triggers when magnetic field has changed, setting the new values in parameters.
+
+### Methods  {#MagneticFieldSensor-Methods}
+
+{:.methods}
+None
+
+
 ## NearField  {#NearField}
 
 Non-visible component to provide NFC capabilities. For now this component supports the reading