Threshold api docs - 01 (#336)

* Local commit

* Throw on more topics

* Throw in threshold topics for infrared

libs/color-sensor/color.ts

@@ -40,7 +40,7 @@ const enum ColorSensorColor {
 enum LightCondition {
     //% block="dark"
     Dark = sensors.ThresholdState.Low,
-    //$ block="bright"
+    //% block="bright"
     Bright = sensors.ThresholdState.High
 }
 
@@ -245,6 +245,7 @@ namespace sensors {
         //% group="Threshold" blockGap=8 weight=90
         //% value.min=0 value.max=100
         //% sensor.fieldEditor="ports"
+        //% help=sensors/color-sensor/set-threshold
         setThreshold(condition: LightCondition, value: number) {
             if (condition == LightCondition.Dark)
                 this.thresholdDetector.setLowThreshold(value)
@@ -259,6 +260,7 @@ namespace sensors {
         //% blockId=colorGetThreshold block="%sensor|%condition"
         //% group="Threshold" blockGap=8 weight=89
         //% sensor.fieldEditor="ports"
+        //% help=sensors/color-sensor/threshold
         threshold(condition: LightCondition): number {
             return this.thresholdDetector.threshold(<ThresholdState><number>LightCondition.Dark);
         }
@@ -266,9 +268,10 @@ namespace sensors {
         /**
          * Collects measurement of the light condition and adjusts the threshold to 10% / 90%.
          */
-        //% blockId=colorCalibrateLight block="calibrate|%sensor|for %mode|light"
+        //% blockId=colorCalibrateLight block="calibrate|%sensor|for %mode"
         //% group="Threshold" weight=91 blockGap=8
         //% sensor.fieldEditor="ports"
+        //% help=sensors/color-sensor/calibrate-light
         calibrateLight(mode: LightIntensityMode, deviation: number = 8) {
             this.calibrating = true; // prevent events
 

libs/color-sensor/docs/reference/sensors/color-sensor/calibrate-light.md

@@ -0,0 +1,26 @@
+# calibrate Light
+
+Calibrate the thresholds for dark and bright in current lighting conditions.
+
+```sig
+sensors.color1.calibrateLight(LightIntensityMode.Ambient, 0)
+```
+
+Sometimes when external lighting conditions change, the light sensor measures light intensty differently than when its thresholds were set before. You can calibrate the light sensor to adjust the thresholds slightly for current conditions. This is so that both the ``dark`` and ``bright`` threshold conditions happen with a similar amount of light to what you set the thresholds before.
+
+## Parameters
+
+* **mode**: the type of light threshold to calibrate. This is either ``ambient`` or ``reflected`` light.
+* **deviation**: a [number](/types/number) that is the amount of light level change to adjust in a measurement.
+
+## Example
+
+Calibrate the ``dark`` and ``light`` thresholds for the ``color 2`` sensor using reflected light.
+
+```blocks
+sensors.color2.calibrateLight(LightIntensityMode.Reflected)
+```
+
+## See also
+
+[set threshold](/reference/sensors/color-sensor/set-threshold)

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

@@ -12,7 +12,7 @@ The [color](/reference/sensors/color) value returned is one of the colors that t
 
 * a color value for the current color detected by the color sensor. The colors detected are:
 
->* ``none``
+>* ``none``: no color is detected.
 >* ``blue``
 >* ``green``
 >* ``yellow``

libs/color-sensor/docs/reference/sensors/color-sensor/light.md

@@ -32,4 +32,4 @@ forever(function () {
 
 ## See also
 
-[reflected light](/reference/sensors/color-sensor/reflected-light)
+[calibrate light](/reference/sensors/color-sensor/calibrate-light)

libs/color-sensor/docs/reference/sensors/color-sensor/set-threshold.md

@@ -0,0 +1,41 @@
+# set Threshold
+
+Set the threshold value for dark or bright light.
+
+```sig
+sensors.color1.setThreshold(LightCondition.Dark, 0)
+```
+
+Light intensity is measured from `0` (very dark) to `100` (very bright). You can decide what dark and bright mean for your purposes and set a _threshold_ for them. A threshold is a boundary or a limit. If you want a light intensity of `20` mean that it's dark, then you set the sensor threshold for ``dark`` to `20`. Also, if you think that `75` is bright, then you can set the threshold for ``bright`` to that.
+
+After setting a threshold, any event for that light condition won't happen until the amount of light reaches your threshold value:
+
+```block
+sensors.color1.setThreshold(LightCondition.Dark, 20)
+sensors.color1.onLightChanged(LightIntensityMode.Reflected, LightCondition.Dark, function () {
+    brick.showMood(moods.sleeping)
+})
+```
+
+## Parameters
+
+* **condition**: the light intensity threshold to set, ``dark`` or ``bright``.
+* **value**: the value of light intensity for the threshold: `0` for very dark to `100` for very bright.
+
+## Example
+
+Make a daylight alarm. When the ambient light reaches `70` flash the status light and play a sound.
+
+```blocks
+sensors.color3.setThreshold(LightCondition.Bright, 70)
+sensors.color3.onLightChanged(LightIntensityMode.Ambient, LightCondition.Bright, function () {
+    brick.setStatusLight(StatusLight.GreenFlash)
+    for (let i = 0; i < 5; i++) {
+        music.playSoundEffectUntilDone(sounds.mechanicalBackingAlert)
+    }
+})
+```
+
+## See also
+
+[threshold](/reference/sensors/color-sensor/threshold)

libs/color-sensor/docs/reference/sensors/color-sensor/threshold.md

@@ -0,0 +1,27 @@
+# threshold
+
+Get the threshold value for dark or bright light.
+
+```sig
+sensors.color1.threshold(LightCondition.Dark)
+```
+
+Light intensity is measured from `0` (very dark) to `100` (very bright). A _threshold_ sets what dark and bright mean for your purposes. A threshold is a boundary or a limit. If a light intensity of `20` means that it's dark, then the sensor threshold for ``dark`` is `20`. Also, if  `75` means bright, then the threshold value for ``bright`` is `75`.
+
+## Returns
+
+* a [number](/types/number) that is the amount of light set for the threshold. No light (darkness) is `0` and the brightest light is `100`.
+
+## Example
+
+Find out what light level is set as the ``dark`` threshold when a dark light event happens.
+
+```blocks
+sensors.color3.onLightChanged(LightIntensityMode.Reflected, LightCondition.Dark, function () {
+    brick.showValue("DarknessThresholdValue", sensors.color3.threshold(LightCondition.Dark), 1)
+})
+```
+
+## See also
+
+[set threshold](/reference/sensors/color-sensor/set-threshold)

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

@@ -12,7 +12,6 @@ Since the color sensor can accurately detect some basic colors, you can't just t
 
 * **color**: a color to match with a detectable color. The colors to choose from are:
 
->* ``none``
 >* ``blue``
 >* ``green``
 >* ``yellow``
@@ -24,7 +23,6 @@ Since the color sensor can accurately detect some basic colors, you can't just t
 
 * a color value that the color sensor can detect. The detectable colors are:
 
->* ``none``
 >* ``blue``
 >* ``green``
 >* ``yellow``

libs/infrared-sensor/docs/reference/sensors/infrared/proximity-threshold.md

@@ -0,0 +1,32 @@
+# proximity Threshold
+
+Get the proximity threshold for when objects are near and detected.
+
+```sig
+sensors.infraredSensor1.proximityThreshold(InfraredSensorEvent.ObjectNear)
+```
+
+Infrared sensors determine proximity of an object by measuring the intensity of the infrared light reflected from it. The proximity range of measurment is from `0` to `100`. Proximity _thresholds_ use a value in this range to decide when a proximity event should happen for a detected object.
+
+## Parameters
+
+* **condition**: the proximity threshold to return a value for. These are: ``near`` and ``detected``.
+
+## Returns
+
+* a [number](/types/number) that is the proximity value for the threshold. This is a number between `0` and `100`.
+
+## Example
+
+When an object with near proximity is detected, show what the threshold is.
+
+```blocks
+sensors.infraredSensor1.onEvent(InfraredSensorEvent.ObjectNear, function () {
+    brick.showValue("NearObjectThreshold", sensors.infraredSensor1.proximityThreshold(InfraredSensorEvent.ObjectNear)
+, 1)
+})
+```
+
+## See also
+
+[set proximity threshold](/reference/sensors/infrared/set-proximity-threshold)

libs/infrared-sensor/docs/reference/sensors/infrared/set-proximity-threshold.md

@@ -0,0 +1,35 @@
+# set Proximity Threshold
+
+Set the proximity threshold for when objects are near or detected.
+
+```sig
+sensors.infraredSensor1.setPromixityThreshold(InfraredSensorEvent.ObjectNear, 0)
+```
+
+Infrared sensors determine proximity of an object by measuring the intensity of the infrared light reflected from it. The proximity range of measurment is from `0` to `100`. You can decide what value in that range you want mean that something is near or that something was detected.
+
+If you want a proximity value of `32` to mean that a detected object is near, then the ``near`` threshold is set to that value. If you want any object within a proximity of `95` to cause a detection event, then the ``detected`` threshold is set to `95`.
+
+## Parameters
+
+* **condition**: the threshold condition to use this proximity. These are: ``near`` and ``detected``.
+* **value**: a proximity [number](/types/number) to set the threshold for.
+
+## Example
+
+Set a threshold for detecting something moving within a proximity `30`. Wait for an object to show up. When it does, flash the status light and make noise as an alarm.
+
+```blocks
+sensors.infraredSensor1.setPromixityThreshold(InfraredSensorEvent.ObjectDetected, 30)
+sensors.infraredSensor1.pauseUntil(InfraredSensorEvent.ObjectDetected)
+brick.clearScreen()
+brick.showString("Perimeter Breach!!!", 3)
+brick.setStatusLight(StatusLight.RedFlash)
+for (let i = 0; i < 10; i++) {
+    music.playSoundEffectUntilDone(sounds.mechanicalHorn2)
+}
+```
+
+## See also
+
+[proximity threshold](/reference/sensors/infrared/proximity-threshold)

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

@@ -0,0 +1,37 @@
+# set Threshold
+
+Set the distance threshold for when objects are near, far, or detected.
+
+```sig
+sensors.ultrasonic1.setThreshold(UltrasonicSensorEvent.ObjectDetected, 0)
+```
+
+Whether something is near or far away really depends on the situation. A object moving towards you is "near" at further distance than something that isn't moving due to the time necessary to move out of its way. So, in certain situations you may want change which distances mean near or far.
+
+You can change the distances for near and far by setting their _thresholds_. A threshold is a boundary or a limit. If you wanted near to mean anything that's closer that 20 centimeters, then that is your threshold for ``near``. Also, if anything further than 35 centimeters is thought of as far, then the threshold for ``far`` is `35`.
+
+Similarly, if you are just concerned about knowing that something has moved within a distance from you, then you set that distance as the threshold for ``detected``.
+
+## Parameters
+
+* **condition**: the threshold condition to set a distance for. These are: ``near``, ``far``, and ``detected``.
+* **value**: a [number](/types/number) that the distance in centimeters to set the threshold for.
+
+## Example
+
+Set a threshold for detecting something moving within 30 centimeters. Wait for an object to show up. When it does, flash the status light and make noise as an alarm.
+
+```blocks
+sensors.ultrasonic1.setThreshold(UltrasonicSensorEvent.ObjectDetected, 30)
+sensors.ultrasonic1.pauseUntil(UltrasonicSensorEvent.ObjectDetected)
+brick.clearScreen()
+brick.showString("Perimeter Breach!!!", 3)
+brick.setStatusLight(StatusLight.RedFlash)
+for (let i = 0; i < 10; i++) {
+    music.playSoundEffectUntilDone(sounds.mechanicalHorn2)
+}
+```
+
+## See also
+
+[threshold](/reference/sensors/ultrasonic/threshold)

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

@@ -0,0 +1,35 @@
+# threshold
+
+Get the distance threshold for when objects are near, far, or detected.
+
+```sig
+sensors.ultrasonic1.threshold(UltrasonicSensorEvent.ObjectDetected)
+```
+
+Whether something is near or far away really depends on the situation. A object moving towards you is "near" at further distance than something that isn't moving due to the time necessary to move out of its way.
+
+Distances for near and far by have set _thresholds_. A threshold is a boundary or a limit. If near means anything that's closer that 20 centimeters, then the threshold for ``near``. Also, if anything further than 35 centimeters is thought of as far, then the threshold for ``far`` is `35`.
+
+Also, the threshold for nowing that something has moved within a distance from you is set for ``detected``.
+
+## Parameters
+
+* **condition**: the condition to get the threshold distance for. These are: ``near``, ``far``, and ``detected``.
+
+## Returns
+
+* a [number](/types/number) that is the threshold distance in centimeters.
+
+## Example
+
+When a near object is detected, show what the threshold is.
+
+```blocks
+sensors.ultrasonic4.onEvent(UltrasonicSensorEvent.ObjectNear, function () {
+    brick.showValue("NearObjectThreshold", sensors.ultrasonic4.threshold(UltrasonicSensorEvent.ObjectNear), 1)
+})
+```
+
+## See also
+
+[set threshold](/reference/sensors/ultrasonic/set-threshold)