Introduction to developing for MicroPython — MicroPython API design and methods
Introduction
MicroPython is a scripting language whereas C/C++ is not, so there are a lot of rules we have to follow to make the Python compiler understand our C code.
API Design
Let’s take
ADC module as an example,
STATIC mp_obj_t adc_read(mp_obj_t self_in) {
adc_obj_t *self = self_in;
uint16_t value = analogin_read_u16(&(self->obj));
return mp_obj_new_int(value);
}
STATIC MP_DEFINE_CONST_FUN_OBJ_1(adc_read_obj, adc_read);
There are a few things to take note:
1. Almost all MicroPython API has to be declared as “STATIC mp_obj_t” return type
This is so to make sure the return type is a void pointer and thus can be easily utilized by MicroPython core and casted to other data type if needed
2. Always return using built-in return function
In the 4th line of the code above, we see the unsigned integer 16-bit variable value was returned using “mp_obj_new_int” API, this API can be found in “obj.h” file.
Since the return type is void pointer, so we have to use these API found in obj.h to type cast it to the correct format and then pass back to user.
3. This API adc_read takes in an mp_obj_t parameter — self_in
This step is not compulsory and is essential if you want a stable structure, as self_in was previsouly pointed to an instance of a structure whose first element is of type of mp_obj_base_t, this is an essential element while MicroPython’s compiler is working.
However, the API’s parameter can take many different forms to cater to various situation, this is a huge topic and will be discussed in the future.
4. The API was linked to its dedicated object using MP_DEFINE_CONST_FUN_OBJ_1
In the last line of the above code, we can see adc_read was linked to adc_read_obj using MP_DEFINE_CONST_FUN_OBJ_1( ) API, this MicroPython built-in API not only do the linking but also tell the compiler that this API only takes in 1 parameter, thus if your API needs 2 paramenter, you need to use MP_DEFINE_CONST_FUN_OBJ_2 instead, so on and so forth.
5. The body of the API follows the same rules as normal C function
Step 3 and Step 4 is a huge topic
As Python can handle same API with different types, numbers and names of parameter, handling this in MicroPython is also required.
