From 7bd2192a0ae41798b0ed42436f6205746843eb02 Mon Sep 17 00:00:00 2001 From: Galen Nickel Date: Sun, 11 Feb 2018 09:01:46 -0800 Subject: [PATCH] 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 | 6 ++- docs/reference/sensors.md | 10 ++++- .../docs/reference/sensors/ultrasonic.md | 13 +++++++ .../reference/sensors/ultrasonic/distance.md | 30 ++++++++++++++ .../reference/sensors/ultrasonic/on-event.md | 39 +++++++++++++++++++ .../sensors/ultrasonic/pause-until.md | 38 ++++++++++++++++++ libs/ultrasonic-sensor/ultrasonic.ts | 6 +-- 7 files changed, 137 insertions(+), 5 deletions(-) create mode 100644 libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic.md create mode 100644 libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic/distance.md create mode 100644 libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic/on-event.md create mode 100644 libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic/pause-until.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 78d3dc98..f1c14cb8 100644 --- a/docs/SUMMARY.md +++ b/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) \ No newline at end of file + * [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) \ No newline at end of file diff --git a/docs/reference/sensors.md b/docs/reference/sensors.md index befa367c..80e93db5 100644 --- a/docs/reference/sensors.md +++ b/docs/reference/sensors.md @@ -15,4 +15,12 @@ sensors.touch1.isPressed() sensors.gyro1.angle(); sensors.gyro1.rate(); sensors.gyro1.reset(); -``` \ No newline at end of file +``` + +## Ultrasonic + +```cards +sensors.ultrasonic4.onEvent(UltrasonicSensorEvent.ObjectDetected, function () {}); +sensors.ultrasonic1.distance(); +sensors.ultrasonic1.pauseUntil(UltrasonicSensorEvent.ObjectDetected); +``` diff --git a/libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic.md b/libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic.md new file mode 100644 index 00000000..86462fb5 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic/distance.md b/libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic/distance.md new file mode 100644 index 00000000..395ed397 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic/on-event.md b/libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic/on-event.md new file mode 100644 index 00000000..a6413f3b --- /dev/null +++ b/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) \ No newline at end of file diff --git a/libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic/pause-until.md b/libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic/pause-until.md new file mode 100644 index 00000000..ed7cf336 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/libs/ultrasonic-sensor/ultrasonic.ts b/libs/ultrasonic-sensor/ultrasonic.ts index 36452e38..ff8019ef 100644 --- a/libs/ultrasonic-sensor/ultrasonic.ts +++ b/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"