Merge pull request #302 from microbit-foundation/nav-updates

update docs for consolidated navigation

Author: microbit-mark

bluetooth/index.md

@@ -11,7 +11,7 @@ lang: en
 
 ## Overview
 
-The micro:bit processor has an on-board [Bluetooth](http://blog.bluetooth.com/a-developers-guide-to-bluetooth/) transceiver. This is combined with a PCB trace aerial and other minor components alongside a software stack that gives the micro:bit a certified and credible Bluetooth capability.
+The micro:bit processor has an on-board [Bluetooth](https://www.bluetooth.com/specifications/) transceiver. This is combined with a PCB trace aerial and other minor components alongside a software stack that gives the micro:bit a certified and credible Bluetooth capability.
 
 ## Bluetooth software stack
 
@@ -20,9 +20,68 @@ The micro:bit processor has an on-board [Bluetooth](http://blog.bluetooth.com/a-
 
 Using Bluetooth, you can connect to other devices and send and receive data from and to the micro:bit.
 
-## micro:bit Bluetooth Features
+Bluetooth is [distinct from the micro:bit to micro:bit radio feature](https://support.microbit.org/support/solutions/articles/19000083637-using-the-micro-bit-wirelessly-),which is a [proprietary protocol from Nordic and Lancaster University](https://lancaster-university.github.io/microbit-docs/ubit/radio/).
+
+## BBC micro:bit Bluetooth Profile
+
+The micro:bit supports Bluetooth via a single, custom-developed, BBC micro:bit profile. This profile allows it to communicate with other BLE capable devices.
+
+## CODAL
+
+A pre-compiled hex file is available to download for <span class="v2">V2</span> that enables all Bluetooth services. 
+
+[Bluetooth all services CODAL](/docs/bluetooth/assets/BLE_All_Services_CODAL_0-0-24-ABDLIMTU-P.hex){: .btn.sm-btn download}
+
+The source for this can be found in the [microbit-v2-samples]https://github.com/lancaster-university/microbit-v2-samples/tree/master/source/samples repository.
+
+### DAL
+
+The BBC micro:bit <span class="v1">V1</span> [Bluetooth profile is defined in the DAL](https://lancaster-university.github.io/microbit-docs/ble/profile/)
+
+You can flash one of two pre-compiled Hex files to the micro:bit <span class="v1">V1</span> that enable bluetooth services. As Bluetooth is memory intensive, these are supplied as either 'without Magnetometer Service' or 'without DFU Service':
+
+[Without magnetometer](/docs/bluetooth/assets/BLE_All_Services_DAL_2-1-1-No-Mag.hex){: .btn.sm-btn download}
+
+[Without DFU](/docs/bluetooth/assets/BLE_All_Services_DAL_2-1-1-No-DFU.hex){: .btn.sm-btn download}
+
+The DAL contains the [C++ source for the BLE service files](https://github.com/lancaster-university/microbit-samples/blob/master/source/examples/bluetooth-services/main.cpp)
+
+There are also some example programs in the [microbit-samples](https://github.com/lancaster-university/microbit-samples) repository:
+
+- [bluetooth-eddystone-uid](https://github.com/lancaster-university/microbit-samples/tree/master/source/examples/bluetooth-eddystone-uid)
+
+- [bluetooth-eddystone-url](https://github.com/lancaster-university/microbit-samples/tree/master/source/examples/bluetooth-eddystone-url)
+
+- [bluetooth-uart](https://github.com/lancaster-university/microbit-samples/tree/master/source/examples/bluetooth-uart)
+
+The micro:bit has a <span class="v2">V2</span>Bluetooth 5.0/<span class="v1">V1</span>Bluetooth 4.1 stack with Bluetooth Low Energy (BLE) and supports the <span class="v1">V1</span>[GAP Peripheral Role](https://bluetooth-developer.blogspot.com/2016/07/microbit-and-bluetooth-roles.html) and <span class="v2">V2</span> GAP Peripheral and Central device roles.
+
+It operates in the ISM (Industrial Scientific Medical) band, as per all Bluetooth devices. This starts at **2.4GHz and ends at 2.41GHz**. BLE divides the frequency band into 50 x 2MHz bands of which 40 are used. These are called **channels** and numbered **0 to 39**. Channels 37, 38 and 39 are used for "advertising".
+
+When devices are connected, they use the other channels in a particular sequence controlled by a feature called **adaptive frequency hopping**. This helps reduce the impact of congestion from other radio users.
+
+Data transfer rates will only be a few hundred Kilobytes per second at best, and throughput depends on how your application uses the Bluetooth features. Throughput depends on the proportion of system protocol overheads to application data. Lots of small packets containing - for example - temperature data would have a lower data transfer rate than using the UART service.
+
+There are some useful [advanced configuration options in the micro:bit runtime code](https://lancaster-university.github.io/microbit-docs/advanced/#compile-time-options-with-yotta)
+
+## Challenge
+
+It would be possible for anyone with the appropriate knowledge to define and implement other Bluetooth profiles.
+
+We are seeking collaborators to help us define the new profile elements that expose some of the <span class="v2">V2</span> features.
+
+## Further information
+
+- [Martin Woolley's Bluetooth Blog](https://bluetooth-developer.blogspot.com/) has a range of information on using Bluetooth with micro:bit
+
+- [BittySoftware](https://bittysoftware.blogspot.com) has a range of Bluetooth enabled software for the micro:bit
+
+- [Original micro:bit "Out of the Box" experience](https://support.microbit.org/a/solutions/articles/19000021613), including some of the attributes in the Bluetooth Profile
+
+- [Full profile with the display unused](https://lancaster-university.github.io/microbit-docs/resources/microbit-1_4_17_pwr0.zip). If you want to write to the display over bluetooth then you should use this file instead of the 'Out of the Box' hex, which uses the display.
+
+- [micro:bit radio API documentation](https://lancaster-university.github.io/microbit-docs/ubit/radio/)
 
-Bluetooth features available on the micro:bit are defined in a [Bluetooth profile](/bluetooth/profile). The micro:bit supports one, custom-developed profile.
 
 ## Bluetooth and the micro:bit software
 
@@ -35,9 +94,4 @@ The processor also has several non-bluetooth, proprietary modes of operation upo
 - [Android App](https://play.google.com/store/apps/details?id=com.samsung.microbit) facilitates [pairing and flashing programs to the micro:bit](https://support.microbit.org/en/support/solutions/articles/19000051025-pairing-and-flashing-code-via-bluetooth)
 - [iOS App](https://apps.apple.com/gb/app/micro-bit/id1092687276)faciliates [pairing and flashing programs to the micro:bit](https://support.microbit.org/en/support/solutions/articles/19000051025-pairing-and-flashing-code-via-bluetooth)
 - [Swift Playgrounds](https://github.com/microbit-foundation/microbit-swift-playgrounds) contains a Playground Book available in the Swift app and a micro:bit Swift API to develop further resources
-Scratch.
-
-## Further information
-
-- [Bluetooth Specification](https://www.bluetooth.com/specifications/adopted-specifications)
-- [DAL/C++ Bluetooth Reference Documentation](https://lancaster-university.github.io/microbit-docs/ble/profile/#reference-documentation)
+- [Scratch](https://scratch.mit.edu/microbit) supports using a range of micro:bit Bluetooth services via the Scratch Link software and a custom built pairing .hex

bluetooth/profile.md

@@ -64,3 +64,7 @@ MicroPython builds take a firmware.hex image (the MicroPython pre-compiled image
 ## Microsoft MakeCode Editor
 
 Hex files generated by the [MakeCode Editor](https://makecode.microbit.org) have embedded meta-data inside the .hex file. This is a [JSON encoded blob with various data about the script](https://github.com/Microsoft/pxt/blob/437f53ca6311335c7f3f75a062ec1079b4e7806a/docs/source-embedding.md), and also the source code program. This may be compressed, and it is stored inside the flash memory of the micro:bit (but only if space is available in the flash memory). But it is always inside the .hex file. This embedded source code program ensures that when you drag and drop the .hex file onto the originating editor, it can recover the source program again.
+
+## Reading out a hex file
+
+If you want to [read out the .hex file](https://www.embeddedlog.com/ubittool/usage.html) currently on your micro:bit, you can do so using [uBitTool](https://www.embeddedlog.com/ubittool).

hardware/power-consumption.md

@@ -108,9 +108,7 @@ Each of the coding environments generates a special file called a .hex file, whi
 
 The micro:bit code is updated by dragging a .hex file onto the MICROBIT drive that appears on your computer, when you plug in the micro:bit. It looks just like a USB memory stick to your computer (the flash drive is actually emulated by the [DAPLink](/software/daplink-interface) software)
 
-It is also possible to 'flash' code to your micro:bit by using a mobile app, and using the Bluetooth communications interface from your mobile phone.
-
-You can read more about [bluetooth flashing](/bluetooth/profile) or [bluetooth apps](/bluetooth/apps-and-examples) by following these links.
+It is also possible to 'flash' code to your micro:bit by using a mobile app, and using the [Bluetooth](/bluetooth/) communications interface from your mobile phone.
 
 ### micro:bit Low Level (C/C++) Software Stack
 

software/assets/browser-build-pipeline.png

@@ -26,6 +26,24 @@ This target depends on several other repositories:
 - <https://github.com/lancaster-university/microbit> basic wrapper around the DAL
 - <https://github.com/lancaster-university/microbit-dal> the micro:bit DAL
 
+## Compiler
+
+ MakeCode uses a built-in compiler to translate a project into a .hex file when you select **Download**.
+
+This has the advantage of not requiring an internet connection in order to code the micro:bit. Once the browser editor at [makecode.microbit.org](https://makecode.microbit.org) loads, it is cached on your computer.
+
+The MakeCode editors contain a copy of the micro:bit runtime [the DAL/CODAL](/software/runtime) which the blocks and javascript APIs reference.
+
+When you press **Download** the compiler converts the code into a machine readable [hex file format](/software/hex-format).
+
+When this .hex file is flashed onto the MICROBIT drive, the KL26/7 interface processor on the micro:bit copies it into the flash memory inside the nRF application processor and the code runs.
+
+## Other Features
+
+MakeCode supports two-way conversion of code, so you can write code as blocks and see what the generated code looks like in Javascript/MakeCode Python. You can also write Javascript/MakeCode Python code, and if possible, MakeCode will convert this back into blocks automatically.
+
+MakeCode also allows you to [write your own block types](https://makecode.com/extensions) and [publish them as Extensions](https://makecode.microbit.org/extensions).
+
 ## App
 
 An app is available for [Windows 10](https://www.microsoft.com/en-gb/p/makecode-for-micro-bit/9pjc7sv48lcx?rtc=1&activetab=pivot:overviewtab)

software/hex-format.md

@@ -21,24 +21,19 @@ The Python editor is based upon the [Ace editor](http://ace.c9.io) and includes
 
 The upstream source code for the Python Editor can be found at [github.com/bbcmicrobit/PythonEditor](https://github.com/bbcmicrobit/PythonEditor)
 
-The micro:bit target depends a closed source versioning repository that facilitates releases at `/v/`, for example the beta editor https://python.microbit.org/v/beta and previous releases.
+The micro:bit target depends a closed source versioning repository that facilitates releases at `/v/`, for example the beta editor [https://python.microbit.org/v/beta](https://python.microbit.org/v/beta) and previous releases.
 
 ### Offline
 
 It is possible to use the Python Editor offline to generate, upload and download .hex or .py files. However, refreshing the browser resets the editor.
 
-### Mu
-
-[Mu](http://codewith.mu/) is a third party Python editor, that provides a downloadable, offline coding experience for the micro:bit and includes features such as datalogging and code debugging.
-
 ### Documentation
 
 - [MicroPython reference](https://microbit-micropython.readthedocs.io/en/v1.0.1/) provides information and examples on using the blocks
 - [Developer setup](https://github.com/bbcmicrobit/PythonEditor/blob/master/README.rst)
 - [Filesystem](https://github.com/bbcmicrobit/PythonEditor/blob/master/docs/filesystem.md)
 - [Translation strategy](https://github.com/bbcmicrobit/PythonEditor/blob/master/docs/translations.md)
 - [Embedding the editor](https://github.com/bbcmicrobit/PythonEditor/blob/master/docs/embedEditor.md)
-- [MakeCode Technical Docs](https://makecode.com/docs) for general development
 
 ### Community