Merge pull request #525 from Microsoft/panic-codes-doc

Document additional panic codes.

docs/device/error-codes.md

@@ -1,11 +1,16 @@
 # Error codes
 
-Your micro:bit may encounter a situation that prevents it from running your code. When this happens, a frowny face will appear on your micro:bit screen (see picture) followed by an error number.
+Your @boardname@ may encounter a situation that prevents it from running your code. When this happens, a frowny face will appear on your @boardname@ screen (see picture) followed by an error number. These are called _panic_ codes.
 
 Below is a list of error numbers and what they mean:
 
-* **10** (`MICROBIT_I2C_LOCKUP`): the micro:bit's I2C bus is not working
-* **20** (`MICROBIT_OOM`): there is no free memory on the micro:bit
+* **10** (`MICROBIT_I2C_LOCKUP`): the @boardname@'s I2C bus is not working
+* **20** (`MICROBIT_OOM`): there is no free memory on the @boardname@
+* **30** (`MICORBIT_HEAP_ERROR`): a problem in the heap space.
+* **40** (`MICROBIT_NULL_DEREFERENCE `): there was a NULL dereference, the @boardname@ tried to manage a invalid object pointer.
+* **42** (`MICROBIT_SYSTEM_ERROR`): there's an error condition in the @boardname@ system software.
+* **43** (`MICROBIT_NO_RADIO`): the @boardname@ can't enable the radio.
+* **98** (`MICROBIT_ASSERTION_FAILED`): assertion failed, the condition in an [assert](/reference/control/assert) was false.
 
 ```sim
 basic.showLeds(`
@@ -19,5 +24,4 @@ basic.showLeds(`
 
 ### See also
 
-[Run scripts on your micro:bit](/device/usb)
-
+[panic](/reference/control/panic), [assert](/reference/control/assert),

docs/reference/control/assert.md

@@ -0,0 +1,29 @@
+# assert
+
+Stop the program if the assertion condition is false.
+
+```sig
+control.assert(false)
+```
+
+You can insist that your program will stop at an assert block if a certain condition you check is false. The error number in the assert is written to the serial port with a failure message.
+
+## Parameters
+
+* **cond**: a [boolean](/types/boolean) where true means everything is ok or false which means, stop the program!
+* **msg**: an optional [string](/types/string) with a message describing the failed assertion.
+
+## Example
+
+Stop the program if a sensor connected to pin `P0` sends a low (`0`) signal.
+
+```blocks
+basic.forever(() => {
+    control.assert(pins.digitalReadPin(DigitalPin.P0) == 1)
+    basic.pause(1000)
+})
+```
+
+## See also
+
+[panic](/reference/control/panic)

docs/reference/control/panic.md

@@ -0,0 +1,40 @@
+# panic
+
+Display an error number and stop the program.
+
+```sig
+control.panic(0)
+```
+
+If your board has some way to display error information, ``||control:panic||`` will work
+with it to show error numbers.
+
+Your program stops when you use ``||control:panic||``. Use this when you think something bad enough has
+happened and your program can't run properly anymore.
+
+## Parameters
+
+* **code**: an error [number](/types/number) you match to an error situation in your program.
+
+### ~hint
+**System error codes**
+
+The @boardname@ has error codes reserved for use by the system software. The ```panic()``` function is for advanced usage only. You must carefully chose an error code that doesn't match one currently used by the @boardname@ system.
+### ~
+
+## Example
+
+Send a 'code red' error that you created to the error display if the input from pin `P0` is lower than `10`.
+
+```blocks
+let codeRed = 1110;
+let codeBlue = 1111;
+
+if (pins.analogReadPin(AnalogPin.P0) < 10) {
+    control.panic(codeRed)
+}
+```
+
+## See also
+
+[assert](/reference/control/assert), [error codes](/device/error-codes)