Auto-generation of library files
The APIs visible to PXT user (as TypeScript functions/classes or blocks)
expose behaviors defined in the C++ library files (in case of hardware targets)
and also the JavaScript simulator (runtime environment).
These are defined in TypeScript files (usually .d.ts) under /libs folder
in the target definition. Let’s call these shim files.
The definitions in shim files include JSDoc comments and
annotations starting with //%. In particular, //% shim=foo::bar means
that the current function should be mapped to the C++ function foo::bar
and also to the simulator function pxsim.foo.bar.
PXT can generate shim files from either C++
in case of hardware targets, or from the simulator sources.
In both cases, PXT will copy over all JSDoc style comments and //% annotations,
add shim=... annotation, and also map the type appropriately (for example, C++ int type
is mapped to number, and TypeScript RefAction to ()=>void).
We refer to the information copied as API meta-data.
Auto-generation from C++
In case of hardware targets, the API meta-data should be defined in C++, and not the simulator. This is mostly because debugging mismatches on the C++ side is much harder than on the JS side.
The shims are generated per-package under /libs when building the target.
The shims files are called shims.d.ts and enums.d.ts. Enums are generated
separately, so that they can be <referenced ...> from simulator sources.
Both files should be listed in "files" section of pxt.json, and we also recommend
they are checked into git.
PXT implements a simple parser for a fragment of C++. This parser will not handle
everything you throw at it. In particular, it is line based and doesn’t take
multi-line comments (other than doc comments) very well. To comment out a piece of C++
code use #if 0 .... #endif.
The type mapping from C++ to TypeScript is quite limited. Checkout the microbit target for an example.
Auto-generation from the simulator
This should be used in case of software-only targets.
The shim file is called sims.d.ts and is generated from /sim/*.ts while building
the target. The file will be generated in the "corepkg" of the target. In future, we may
allow splitting between packages. Similarly, to the C++ generation, sims.d.ts should
be included in pxt.json and checked in.
Checkout the sample target for an example.
functionAsync handling
A function (or method) named fooAsync will be exposed as foo. It is expected
to return a promise. This will generate //% promise annotation, which will let
the compiler know about this calling convention.
Legacy async handling
The simulator function can also get hold of a callback function using getResume()
and then call the resulting function when the function is supposed to resume.
You need to include the //% async annotation in that case.
Simulator implementations
If you’re adding your own C++ or assembly functions in packages and you either cannot or don’t want to add a corresponding function to the simulator, you can provide a simulator-only implementation. For example:
/**
* Writes to the Bluetooth UART service buffer.
*/
//% blockId=bluetooth_uart_write block="bluetooth uart write %data" blockGap=8
//% shim=bluetooth::uartWrite
export function uartWrite(data: string): void {
// dummy implementation for simulator
console.log("UART Write: " + data)
}Notice the shim= annotation. In C++ you would have just this:
namespace bluetooth {
//%
void uartWrite(StringData *data) {
// ...
}
} When PXT sees a call to function annotated with shim=, it will always use the
shim in the native compilation. In simulator compilation it will use the shim only
if the function has no body or empty body. If you don’t want your simulator implementation
to do anything, you can for example put a single return statement as the body.
Indexed Instances
A typical pattern to expose pins on a device is something like follows:
class DeviceIO {
public:
DevicePin pins[0];
//% indexedInstanceNS=pins indexedInstanceShim=pins::getPin
//%
DevicePin A0;
//%
DevicePin A1;
...
};
namespace pins {
DeviceIO io;
//%
DevicePin *getPin(int id) {
// ... add range checking ...
return &io.pins[id];
}
}
namespace DevicePinMethods {
//% blockId=device_get_digital_pin block="digital read|pin %name" blockGap=8
//% blockNamespace=pins
int digitalRead(DevicePin *name) {
return name->getDigitalValue()
}
...
}This will result in the following declarations being generated:
declare namespace pins {
//% fixedInstance shim=pins::getPin(0)
const A0: DevicePin;
//% fixedInstance shim=pins::getPin(1)
const A1: DevicePin;
...
}
declare interface DevicePin {
//% blockId=device_get_digital_pin block="digital read|pin %name" blockGap=8
//% blockNamespace=pins shim=DevicePinMethods::digitalRead
digitalRead(): number;
...
}The indexedInstanceShim generates the shim=...(no) annotations.
They instruct the access to the variable (which is read-only) to be
compiled as a call to the specified function with the specific literal
argument. The fixedInstance annotation is automatically generated
for blocks.
The namespace FooMethods is turned into an interface Foo. These
are usually used to wrap native C++ classes that require no reference
counting. Thus, you also need to manually add the following TypeScript:
interface DevicePin {
// no methods needed, they come from C++
}If you don’t, the runtime will call methods that don’t exist and chaos will prevail (even though you might not see it at the beginning).
You can also specify inheritance in such a declaration:
interface AnalogPin extends DigitalPin {}Configuring instances from TypeScript
The method above with indexedInstanceShim works well when the set of instances
(eg. pins) is defined in C++. However, sometimes you will want to define these on the
TypeScript side, potentially limiting code size, and allowing the definitions to be
changed without altering the C++ code (and thus avoiding cloud recompilation).
This comes in handy especially when there are multiple boards defined in one target.
The core board package includes at least two configuration files. Here,
we use device.d.ts and config.ts, but you can call them something else.
You would then use something like this:
// In device.d.ts
declare namespace pins {
//% fixedInstance shim=pxt::getPinById(PIN_A0)
const A0: PwmPin;
//% fixedInstance shim=pxt::getPinById(PIN_A1)
const A1: PwmPin;
// ...
}The C++ function pxt::getPinById(int pinId) would lookup a pin object given its hardware
name, allocating the object first if it hasn’t been allocated yet.
The definition of PIN_A0 etc. comes in config namespace:
// In config.ts
namespace config {
export const PIN_A0 = DAL.PA02;
export const PIN_A1 = DAL.PB08;
// ...
export const NUM_NEOPIXELS = 1;
// ...
}You can configure pin names and other hardware characteristics too, like the number of on-board neopixels, etc.
The user can override the constants using the userconfig namespace. For example:
// In main.ts or other user file
namespace userconfig {
// My board has PIN_D2 and PIN_D4 swapped!
export const PIN_D2 = DAL.PA08;
export const PIN_D4 = DAL.PA14;
}Both of these refer to constants from the DAL namespace. There is typically one
dal.d.ts file per target which defines the DAL namespace, and it is generated
automatically from the C++ sources. Once all the C++ files are in place, and you
want to force re-generation of dal.d.ts, use the pxt builddaldts command.
For every constant FOO in config (or userconfig), there has to be a corresponding
DAL.CFG_FOO that defines an index under which the configuration setting is stored.
The indexes for settings can be any 32 bit number, but they should be unique within a target.
These are typically defined in a C++ header file:
#define CFG_PIN_A0 100
#define CFG_PIN_A1 101
#define CFG_PIN_A2 102
// ...
#define CFG_NUM_NEOPIXELS 200
// ...On the C++ side, the setting PIN_A0 is accessed with pxt::getConfig(CFG_PIN_A0).
The arguments in annotations like shim=pxt::getButtonByPin(PIN_A5,BUTTON_ACTIVE_LOW_PULL_UP)
are resolved in the DAL namespace, then in userconfig and in config.
They must resolve to an integer constant.