Fill in some ultrasonic sensor topics (#321)

* Fill in some ultrasonic sensor topics

* Busted link

* Adjust those sea also links

* Busted snippets

docs/SUMMARY.md

@@ -77,4 +77,8 @@
         * [Gyro](/reference/sensors/gyro)
             * [angle](/reference/sensors/gyro/angle)
             * [rate](/reference/sensors/gyro/rate)
-            * [reset](/reference/sensors/gyro/reset)
+            * [reset](/reference/sensors/gyro/reset)
+        * [Ultrasonic](/reference/sensors/ultrasonic)
+            * [on event](/reference/sensors/ultrasonic/on-event),
+            * [distance](reference/sensors/ultrasonic/distance),
+            * [pause until](reference/sensors/ultrasonic/pause-until)

docs/reference/sensors.md

@@ -15,4 +15,12 @@ sensors.touch1.isPressed()
 sensors.gyro1.angle();
 sensors.gyro1.rate();
 sensors.gyro1.reset();
-```
+```
+
+## Ultrasonic
+
+```cards
+sensors.ultrasonic4.onEvent(UltrasonicSensorEvent.ObjectDetected, function () {});
+sensors.ultrasonic1.distance();
+sensors.ultrasonic1.pauseUntil(UltrasonicSensorEvent.ObjectDetected);
+```

libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic.md

@@ -0,0 +1,13 @@
+# Ultrasonic sensor
+
+```cards
+sensors.ultrasonic4.onEvent(UltrasonicSensorEvent.ObjectDetected, function () {});
+sensors.ultrasonic1.distance();
+sensors.ultrasonic1.pauseUntil(UltrasonicSensorEvent.ObjectDetected);
+```
+
+## See Also
+
+[on event](/reference/sensors/ultrasonic/on-event),
+[distance](reference/sensors/ultrasonic/distance),
+[pause until](reference/sensors/ultrasonic/pause-until)

libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic/distance.md

@@ -0,0 +1,30 @@
+# distance
+
+The distance of an object detected by the ultrasonic sensor.
+
+```sig
+sensors.ultrasonic1.distance()
+```
+
+The distance value returned is the number of centimeters to the object that the sensor is currently detecting.
+
+## Returns
+
+* a [number](/types/number) that is the distance of the object detected by the ultrasonic sensor in centimeters.
+
+
+## Example
+
+When the ultrasonic sensor on port 4 detects a far object, display its distance on the screen.
+
+```blocks
+sensors.ultrasonic4.onEvent(UltrasonicSensorEvent.ObjectFar, function () {
+    brick.showString("Object detected at:", 1)
+    brick.showNumber(sensors.ultrasonic4.distance(), 2)
+    brick.showString("centimeters", 3)
+})
+```
+
+## See also
+
+[on event](/reference/sensors/ultrasonic/on-event), [pause until](/reference/sensors/ultrasonic/pause-until)

libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic/on-event.md

@@ -0,0 +1,39 @@
+# on Event
+
+Run some code when an object is detected by the ultrasonic sensor.
+
+```sig
+sensors.ultrasonic1.pauseUntil(UltrasonicSensorEvent.ObjectDetected);
+```
+
+How an object is detected depends on the distance and movement _thresholds_ set for the sensor. A threshold is a number that is some distance in centimeters or the strength of ultrasonic sound. You can set a distance to detect something that is far, near, or is sending out ultrasound (like the sensor of another robot in the area). The three thresholds you can set are:
+
+* **near**: a distance to set to detect objects coming close
+* **far**: a distance to set to detect objects farther away but not as close as the **near** threshold
+* **detected**: the strength of ultrasound to needed to detect presence of another ultrasonic sensor
+
+Both **near** and **far** have distance thresholds set in centimeters. The **detect** threshold is a value of strength the ultrasonic sound in decibels.
+
+## Parameters
+
+* **event**: the object detection action to wait for. The detection types (events) are:
+> * ``object detected``: some other object is sending out an ultrasonic sound
+> * ``object near``: the sensor detected something within the distance of the near threshold
+> * ``object far``: the sensor detected somethin within the distance of the far threshold
+* **body**: the code you want to run when something happens to the touch sensor.
+
+## Example
+
+When the ultrasonic sensor on port 4 detects a far object, display its distance on the screen.
+
+```blocks
+sensors.ultrasonic4.onEvent(UltrasonicSensorEvent.ObjectFar, function () {
+    brick.showString("Object detected at:", 1)
+    brick.showNumber(sensors.ultrasonic4.distance(), 2)
+    brick.showString("centimeters", 3)
+})
+```
+
+## See also
+
+[pause until](/reference/sensors/ultrasonic/pause-until)

libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic/pause-until.md

@@ -0,0 +1,38 @@
+# pause Until
+
+Make your program wait until an some object is detected in proximity of the sensor.
+
+```sig
+sensors.ultrasonic1.pauseUntil(UltrasonicSensorEvent.ObjectDetected);
+```
+
+How an object is detected depends on the distance and movement _thresholds_ set for the sensor. A threshold is a number that is some distance in centimeters or the strength of ultrasonic sound. You can set a distance to detect something that is far, near, or is sending out ultrasound (like the sensor of another robot in the area). The three thresholds you can set are:
+
+* **near**: a distance to set to detect objects coming close
+* **far**: a distance to set to detect objects farther away but not as close as the **near** threshold
+* **detected**: the strength of ultrasound to needed to detect presence of another ultrasonic sensor
+
+Both **near** and **far** have distance thresholds set in centimeters. The **detect** threshold is a value of strength the ultrasonic sound in decibels.
+
+## Parameters
+
+* **event**: the object detection action to wait for. The detection types (events) are:
+> * ``object detected``: some other object is sending out an ultrasonic sound
+> * ``object near``: the sensor detected something within the distance of the near threshold
+> * ``object far``: the sensor detected somethin within the distance of the far threshold
+
+## Example
+
+Wait for another object sending out ultrasonic sound. Show a message on the screen when it's dectected.
+
+```blocks
+brick.showString("Waiting for another", 1);
+brick.showString("robot to appear...", 2);
+sensors.ultrasonic1.pauseUntil(UltrasonicSensorEvent.ObjectDetected);
+brick.showString("Hey, I just heard", 1)
+brick.showString("Something!", 2);
+```
+
+## See also
+
+[on event](/reference/sensors/ultrasonic/on-event)

libs/ultrasonic-sensor/ultrasonic.ts

@@ -41,7 +41,7 @@ namespace sensors {
          * Registers code to run when the given color is close
          * @param handler the code to run when detected
          */
-        //% help=input/ultrasonic/on
+        //% help=sensors/ultrasonic/on-event
         //% blockId=ultrasonicOn
         //% block="on %sensor|%event"
         //% parts="ultrasonicsensor"
@@ -56,7 +56,7 @@ namespace sensors {
         /**
          * Waits for the event to occur
          */
-        //% help=input/ultrasonic/wait
+        //% help=sensors/ultrasonic/pause-until
         //% block="pause until %sensor| %event"
         //% blockId=ultrasonicWait
         //% parts="ultrasonicsensor"
@@ -72,7 +72,7 @@ namespace sensors {
          * Gets the distance from the sonar in centimeters
          * @param sensor the ultrasonic sensor port
          */
-        //% help=input/ultrasonic/distance
+        //% help=sensors/ultrasonic/distance
         //% block="%sensor|distance"
         //% blockId=sonarGetDistance
         //% parts="ultrasonicsensor"