MakeCode extension compatibility

[microbit-sam]

Software running on a new micro:bit uses CODAL (micro:bit V1 uses the DAL) and as a result no longer includes the mbed platform. The whole microbit-DAL API is implemented in CODAL as a compatibility layer so the same code can compile and run on any micro:bit, irrespective of hardware version.

Extensions that do not compile for V2 will still be available for V1 boards, but will be disabled in V2 builds. Users will see a runtime error on the micro:bit V2 (929)

To ease the transistion away from mbed, we have also implemented the most common mbed classes in the compat layers of CODAL. These should work in most use cases, but there may be a few edge cases where the behaviour is not identical - please file CODAL bugs if you encounter this. Extensions are encouraged to move to the DAL/CODAL model, using the uBit object to ensure compatibility with all hardware.

In the future, all extensions should target the common microbit-dal API. We will not approve new extensions that use the mbed compatibility layer.

The mbed classes implemented are DigitalIn, DigitalOut, InterruptIn, Timer, Ticker, Timeout, PwmOut and can be found here.

Problems with compilation break down into roughly three categories:

1. Use of mbed APIs that are in the compatibility layer, but no inclusion of mbed.h

The following mbed classes are implemented in the compatibility layer:
PwmOut, InterruptIn, DigitalIn, DigitalOut, Ticker, Timer

If you rely on any of these classes you now need to explicitly include mbed.h (whereas previousy microbit.h or pxt.h would implicitly include that). For many extensions, just including mbed.h will resolve outstanding compilation failures.

2. Use of mbed APIs that are not included in the compatibility layer, or microbit-dal APIs that need different constructors

If you use any other part of mbed than those listed above, the quickest option is to move to the CODAL APIs right away, either using #ifdef mbcodal to make V2 specific code, or using the microbit-dal API that is common to V1 and V2.

There are some parts of the compatibility layer that we are considering extending to; but these are still WIP - if your extension requires these and this will also reslove future compatibility issues, please respond on this ticket.

• MicroBitI2C / NRF52I2C
• MicroBitSerial
• MicroBitFont

3. Use of the mbed Bluetooth APIs

• Use of mbed BLE
  • The core BLE API behaves the same in CODAL as the DAL, but is implemented by directly using nRF5SDK, without the mbed layer
  • https://github.com/lancaster-university/codal-microbit-v2/tree/master/inc/bluetooth
  • If you are using the existing mbed BLE

Going forward the extension approval process will require extensions to not use mbed.

[microbit-sam]

Typedef MicroBitFont #32

[microbit-sam]

codal::Pin->name is a PinNumber, @finneyj is that correct?

https://github.com/lancaster-university/codal-core/blob/7132daedac411f636df46447025c1e4fcb7bc1e6/inc/driver-models/Pin.h#L100

Appears to be the reason a few extensions aren't compatible with Button

e.g.

/home/build/prjclone/pxtapp/pxt-kitronik-zip-64/zip64.cpp:18:61: error: invalid conversion from 'codal::PinNumber {aka unsigned char}' to 'PinName' [-fpermissive]
 #define ALLOC_PIN_BUTTON(id) new MicroBitButton(getPin(id)->name, id, MICROBIT_BUTTON_ALL_EVENTS, PullUp);

[microbit-sam]

Fix for incompatible types: codal::Pin->name is a PinNumber #34

[microbit-sam]

Fix is in the latest codal-microbit-v2 tag, and will need to be pulled through to MakeCode
2dc5d29

Font, Button, Serial, and I2C compat fixes included

[tianli]

Hi, I'd like to know what is the timeline for extending the compatibility layer to MicroBitSerial? Our library (mu-opensource/pxt-muvision) depends on it for serial communication.

Thanks!

[jaustin]

We have no plans to extend the compatibility layer at this stage, @JohnVidler is preparing a V1.0 release of CODAL shortly and we think the current level of compat is working for most people. Please raise a new issue if there are still things you need.