Gyro sensor topics (#311)

docs/SUMMARY.md

@@ -68,3 +68,7 @@
         * [speed](/reference/motors/motor/speed)
         * [clear counts](/reference/motors/motor/clear-counts)
         * [stop all motors](/reference/motors/stop-all-motors)
+    * [Sensors](/reference/sensors)
+        * [angle](/reference/sensors/gyro/angle)
+        * [rate](/reference/sensors/gyro/rate)
+        * [reset](/reference/sensors/gyro/reset)

docs/reference.md

@@ -2,12 +2,14 @@
 
 ```namespaces
 brick.showMood(moods.sleeping);
-motors.stopAllMotors()
+sensors.color(null);
+motors.stopAllMotors();
 ```
 
 ## See Also
 
 [brick](/reference/brick),
+[sensors](/reference/sensors),
 [motors](/reference/motors),
 [touch sensor](/reference/sensors/touch-sensor),
 [color sensor](/reference/sensors/color-sensor)

docs/reference/sensors.md

@@ -0,0 +1,9 @@
+# Sensors
+
+## Gyro
+
+```cards
+sensors.gyro1.angle();
+sensors.gyro1.rate();
+sensors.gyro1.reset();
+```

libs/gyro-sensor/docs/reference/sensors/gyro/angle.md

@@ -0,0 +1,27 @@
+# angle
+
+Get the current rotation angle of the gyro.
+
+```sig
+sensors.gyro2.rate()
+```
+
+When the brick changes its position, it's moved in the direction of one of the axes used to measure three-dimensional space. Depending on where the gyro sensor is attached, it can measure the difference in angle from where it was before it moved. This angle is measured in degrees. The angle is the number of degrees rotated from where the gyro was last [reset](/reference/sensors/gyro/reset).
+
+## Returns
+
+* a [number](/types/number) that is the current angle of rotation in degrees.
+
+## Example
+
+Turn the brick and press ENTER to see the current rotation angle of `gyro 2`.
+
+```blocks
+brick.buttonEnter.onEvent(ButtonEvent.Pressed, function () {
+    brick.showNumber(sensors.gyro2.angle(), 1)
+})
+```
+
+## See also
+
+[rate](/reference/sensors/gyro/rate), [reset](/reference/sensors/gyro/reset)

libs/gyro-sensor/docs/reference/sensors/gyro/rate.md

@@ -0,0 +1,32 @@
+# rate
+
+Get the current rotation rate from the gyro.
+
+```sig
+sensors.gyro2.rate()
+```
+
+When the brick is in motion, it moves in the direction of one of axes used to measure three-dimensional space. Depending on where the gyro sensor is attached, it can measure the difference in angle from where it was before the last motion occurred. While the brick is moving the angle differences are measured continuously. This gives a rate of change in angle from one point in time to the next. This rate of change is measured as how many degrees of angle change in one second (degrees per second). This also known as _roll rate_ or _angular velocity_.
+
+
+## Returns
+
+* a [number](/types/number) that is the current rate of rotation in degrees per second.
+
+## Example
+
+Flash the status light to red if the roll rate of `gyro 2` is more that `30` degrees per second.
+
+```blocks
+loops.forever(function () {
+    if (sensors.gyro2.rate() > 30) {
+        brick.setStatusLight(StatusLight.RedFlash)
+    } else {
+        brick.setStatusLight(StatusLight.Off)
+    }
+})
+```
+
+## See also
+
+[angle](/reference/sensors/gyro/angle), [reset](/reference/sensors/gyro/reset)

libs/gyro-sensor/docs/reference/sensors/gyro/reset.md

@@ -0,0 +1,39 @@
+# reset
+
+Reset the zero reference for the gyro to current position of the brick.
+
+```sig
+sensors.gyro2.reset()
+```
+
+To make the gyro measure rotation angle from the current position of the brick, it is recalibrated. That is, the brick's current position is set to `0` degrees and rotation angle measurements start from there.
+
+## ~hint
+
+The current position is considered to be the [_horizon_](https://en.wikipedia.org/wiki/Attitude_indicator) or a place that is the _plane of reference_ (this is possibly someplace that's flat for a horizontal reference).
+
+## ~
+
+## ~hint
+
+**Important**
+
+To properly reset the gyro, the brick must remain still (undistrurbed) while the reset operation takes place.
+
+## ~
+
+## Example
+Set the brick on a flat surface. Reset `gyro 2` and tilt the brick slighly. Reset it again while it's still tilted. Lay the brick down flat again and display the angle measurement.
+
+```blocks
+brick.buttonLeft.onEvent(ButtonEvent.Pressed, function () {
+    sensors.gyro2.reset()
+})
+brick.buttonRight.onEvent(ButtonEvent.Pressed, function () {
+    brick.showNumber(sensors.gyro2.angle(), 1)
+})
+```
+
+## See also
+
+[angle](/reference/sensors/gyro/angle), [rate](/reference/sensors/gyro/rate)

libs/gyro-sensor/gyro.ts

@@ -36,7 +36,7 @@ namespace sensors {
          * Get the current angle from the gyroscope.
          * @param sensor the gyroscope to query the request
          */
-        //% help=input/gyro/angle
+        //% help=sensors/gyro/angle
         //% block="%sensor|angle"
         //% blockId=gyroGetAngle
         //% parts="gyroscope"
@@ -56,7 +56,7 @@ namespace sensors {
          * Get the current rotation rate from the gyroscope.
          * @param sensor the gyroscope to query the request
          */
-        //% help=input/gyro/rate
+        //% help=sensors/gyro/rate
         //% block="%sensor|rate"
         //% blockId=gyroGetRate
         //% parts="gyroscope"
@@ -81,7 +81,7 @@ namespace sensors {
         /**
          * Forces a calibration of the gyro. Must be called when the sensor is completely still.
          */
-        //% help=input/gyro/calibrate
+        //% help=sensors/gyro/reset
         //% block="reset %sensor|"
         //% blockId=gyroReset  
         //% parts="gyroscope"