Skip to content

Upgrade based on MicroPython Latest version #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Upgrade based on MicroPython Latest version #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d113a74
update to 1.20.0 to argument parsing
Jul 10, 2023
3fc59a8
update with micropython latest version
Jul 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 9 additions & 37 deletions docs/source/usermods_03.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ as the current working directory.
!cd ../../micropython/ports/unix/
.. parsed-literal::

/home/v923z/sandbox/micropython/v1.11/micropython/ports/unix
/home/v923z/sandbox/micropython/v1.20.0/micropython/ports/unix

The micropython codebase itself is set up a rather modular way. Provided
you cloned the micropython repository with
Expand All @@ -25,11 +25,11 @@ see something like this:
!ls ../../../micropython/
.. parsed-literal::

ACKNOWLEDGEMENTS docs lib pic16bit teensy zephyr
bare-arm drivers LICENSE py tests
cc3200 esp8266 logo qemu-arm tools
CODECONVENTIONS.md examples minimal README.md unix
CONTRIBUTING.md extmod mpy-cross stmhal windows
ACKNOWLEDGEMENTS docs lib pic16bit teensy zephyr
bare-arm drivers LICENSE py tests
cc3200 esp8266 logo qemu-arm tools
CODECONVENTIONS.md examples minimal README.md unix
CONTRIBUTING.md extmod mpy-cross stmhal windows

Out of all the directoties, at least two are of particular interest.
Namely, ``/py/``, where the python interpreter is implemented, and
Expand All @@ -40,44 +40,16 @@ these two directories, and perusing the relevant files therein.
User modules in micropython
---------------------------

Beginning with the 1.10 version of micropython, it became quite simple
Beginning with the 1.20.0 version of micropython, it became quite simple
to add a user-defined C module to the firmware. You simply drop two or
three files in an arbitrary directory, and pass two compiler flags to
``make`` like so:

.. code:: bash

!make USER_C_MODULES=../../../user_modules CFLAGS_EXTRA=-DMODULE_EXAMPLE_ENABLED=1 all
!make USER_C_MODULES=../../../user_modules
Here, the ``USER_C_MODULES`` variable is the location (relative to the
location of ``make``) of your files, while ``CFLAGS_EXTRA`` defines the
flag for your particular module. This is relevant, if you have many
modules, but you want to include only some of them.

Alternatively, you can set the module flags in ``mpconfigport.h`` (to be
found in the port’s root folder, for which you are compiling) as

.. code:: make

#define MODULE_SIMPLEFUNCTION_ENABLED (1)
#define MODULE_SIMPLECLASS_ENABLED (1)
#define MODULE_SPECIALCLASS_ENABLED (1)
#define MODULE_KEYWORDFUNCTION_ENABLED (1)
#define MODULE_CONSUMEITERABLE_ENABLED (1)
#define MODULE_VECTOR_ENABLED (1)
#define MODULE_RETURNITERABLE_ENABLED (1)
#define MODULE_PROFILING_ENABLED (1)
#define MODULE_MAKEITERABLE_ENABLED (1)
#define MODULE_SUBSCRIPTITERABLE_ENABLED (1)
#define MODULE_SLICEITERABLE_ENABLED (1)
#define MODULE_VARARG_ENABLED (1)
#define MODULE_STRINGARG_ENABLED (1)

and then call ``make`` without the ``CFLAGS_EXTRA`` flag:

.. code:: bash

!make USER_C_MODULES=../../../user_modules all
This separation of the user code from the micropython code base is
location of ``make``) of your files. This separation of the user code from the micropython code base is
definitely a convenience, because it is much easier to keep track of
changes, and also because you can’t possibly screw up micropython
itself: you can also go back to a working piece of firmware by dropping
Expand Down
15 changes: 15 additions & 0 deletions docs/source/usermods_04.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,21 @@ called on objects with this new type, i.e.,

will just work. We return to this question later.

An alternative way to check the type of a variable is to use the
``mp_obj_get_type_str`` and use ``strcmp`` to compare the result with.
``strcmp`` is a C function that compares two strings, and returns 0, if
they are equal. So, if we want to check, whether ``some_variable`` is a
integer, we could write:

.. code:: c

if (strcmp(mp_obj_get_type_str(some_variable), "int") == 0) {
// do something
}

This is not the most elegant way to do it, but it is useful, if you
don't know the type of the variable at compile time.

python constants
----------------

Expand Down
42 changes: 10 additions & 32 deletions docs/source/usermods_05.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ https://github.com/v923z/micropython-usermod/tree/master/snippets/simplefunction
.globals = (mp_obj_dict_t*)&simplefunction_module_globals,
};

MP_REGISTER_MODULE(MP_QSTR_simplefunction, simplefunction_user_cmodule, MODULE_SIMPLEFUNCTION_ENABLED);
MP_REGISTER_MODULE(MP_QSTR_simplefunction, simplefunction_user_cmodule);

Header files
------------
Expand Down Expand Up @@ -160,26 +160,12 @@ module with

.. code:: c

MP_REGISTER_MODULE(MP_QSTR_simplefunction, simplefunction_user_cmodule, MODULE_SIMPLEFUNCTION_ENABLED);
MP_REGISTER_MODULE(MP_QSTR_simplefunction, simplefunction_user_cmodule);

This last line is particularly useful, because by setting the
``MODULE_SIMPLEFUNCTION_ENABLED`` variable in ``mpconfigport.h``, you
can selectively exclude modules from the linking, i.e., if in
``mpconfigport.h``, which should be in the root directory of the port
you want to compile for,
This is the function that is called by the interpreter, when the module
is imported. It takes two arguments, the name of the module, and the
module’s globals table, which we have just defined.

.. code:: c

#define MODULE_SIMPLEFUNCTION_ENABLED (1)

then ``simplefunction`` will be included in the firmware, while with

.. code:: c

#define MODULE_SIMPLEFUNCTION_ENABLED (0)

the module will be dropped, even though the source is in your modules
folder. (N.B.: the module will still be compiled, but not linked.)

Compiling our module
--------------------
Expand All @@ -196,30 +182,22 @@ https://github.com/v923z/micropython-usermod/tree/master/snippets/simplefunction
USERMODULES_DIR := $(USERMOD_DIR)

# Add all C files to SRC_USERMOD.
SRC_USERMOD += $(USERMODULES_DIR)/simplefunction.c
SRC_USERMOD_C += $(USERMODULES_DIR)/simplefunction.c

CFLAGS_USERMOD += -I$(USERMODULES_DIR)
If ``mpconfigport.h`` is augmented with

.. code:: make

#define MODULE_SIMPLEFUNCTION_ENABLED (1)

you should be able to compile the module above by calling

.. code:: bash

!make clean
!make USER_C_MODULES=../../../usermod/snippets all
!make USER_C_MODULES=../../../usermod/snippets/simplefunction
As mentioned earlier, if you do not want to touch anything in the
micropython code base, you can simply pass the definition to make as

.. code:: bash

!make clean
!make USER_C_MODULES=../../../usermod/snippets CFLAGS_EXTRA=-DMODULE_SIMPLEFUNCTION_ENABLED=1 all
You will also note that we ran ``make clean`` before the compilation.
This is always good practice, when you are developing your own modules.
shown above. You will also note that we ran ``make clean`` before the
compilation. This is always good practice, when you are developing
your own modules.

We can then test the module as

Expand Down
6 changes: 3 additions & 3 deletions docs/source/usermods_06.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ https://github.com/v923z/micropython-usermod/tree/master/snippets/constants/cons
.globals = (mp_obj_dict_t*)&constants_module_globals,
};

MP_REGISTER_MODULE(MP_QSTR_constants, constants_user_cmodule, MODULE_CONSTANTS_ENABLED);
MP_REGISTER_MODULE(MP_QSTR_constants, constants_user_cmodule);

https://github.com/v923z/micropython-usermod/tree/master/snippets/constants/micropython.mk

Expand All @@ -144,13 +144,13 @@ https://github.com/v923z/micropython-usermod/tree/master/snippets/constants/micr
USERMODULES_DIR := $(USERMOD_DIR)

# Add all C files to SRC_USERMOD.
SRC_USERMOD += $(USERMODULES_DIR)/constants.c
SRC_USERMOD_C += $(USERMODULES_DIR)/constants.c

CFLAGS_USERMOD += -I$(USERMODULES_DIR)
.. code:: bash

!make clean
!make USER_C_MODULES=../../../usermod/snippets CFLAGS_EXTRA=-DMODULE_CONSTANTS_ENABLED=1 all
!make USER_C_MODULES=../../../usermod/snippets/constants
One comment before trying out what we have just implemented: the module
is definitely pathological. If all you need is a set of constants
organised in some way, then you should write it in python. There is
Expand Down
6 changes: 3 additions & 3 deletions docs/source/usermods_07.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ https://github.com/v923z/micropython-usermod/tree/master/snippets/sillyerrors/si
.globals = (mp_obj_dict_t*)&sillyerrors_module_globals,
};

MP_REGISTER_MODULE(MP_QSTR_sillyerrors, sillyerrors_user_cmodule, MODULE_SILLYERRORS_ENABLED);
MP_REGISTER_MODULE(MP_QSTR_sillyerrors, sillyerrors_user_cmodule);

Now, not all exceptions are created equal. Some are more exceptional
than the others: ``ValueError``, ``TypeError``, ``OSError``, and
Expand Down Expand Up @@ -124,13 +124,13 @@ https://github.com/v923z/micropython-usermod/tree/master/snippets/sillyerrors/mi
USERMODULES_DIR := $(USERMOD_DIR)

# Add all C files to SRC_USERMOD.
SRC_USERMOD += $(USERMODULES_DIR)/sillyerrors.c
SRC_USERMOD_C += $(USERMODULES_DIR)/sillyerrors.c

CFLAGS_USERMOD += -I$(USERMODULES_DIR)
.. code:: bash

!make clean
!make USER_C_MODULES=../../../usermod/snippets CFLAGS_EXTRA=-DMODULE_SILLYERRORS_ENABLED=1 all
!make USER_C_MODULES=../../../usermod/snippets/sillyerrors
.. code ::

%%micropython
Expand Down
24 changes: 12 additions & 12 deletions docs/source/usermods_08.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ https://github.com/v923z/micropython-usermod/tree/master/snippets/vararg/vararg.
.globals = (mp_obj_dict_t*)&vararg_module_globals,
};

MP_REGISTER_MODULE(MP_QSTR_vararg, vararg_user_cmodule, MODULE_VARARG_ENABLED);
MP_REGISTER_MODULE(MP_QSTR_vararg, vararg_user_cmodule);

https://github.com/v923z/micropython-usermod/tree/master/snippets/vararg/micropython.mk

Expand All @@ -129,13 +129,13 @@ https://github.com/v923z/micropython-usermod/tree/master/snippets/vararg/micropy
USERMODULES_DIR := $(USERMOD_DIR)

# Add all C files to SRC_USERMOD.
SRC_USERMOD += $(USERMODULES_DIR)/vararg.c
SRC_USERMOD_C += $(USERMODULES_DIR)/vararg.c

CFLAGS_USERMOD += -I$(USERMODULES_DIR)
.. code:: bash

!make clean
!make USER_C_MODULES=../../../usermod/snippets CFLAGS_EXTRA=-DMODULE_VARARG_ENABLED=1 all
!make USER_C_MODULES=../../../usermod/snippets/vararg
.. code ::

%%micropython
Expand Down Expand Up @@ -228,7 +228,7 @@ https://github.com/v923z/micropython-usermod/tree/master/snippets/stringarg/stri
.globals = (mp_obj_dict_t*)&stringarg_module_globals,
};

MP_REGISTER_MODULE(MP_QSTR_stringarg, stringarg_user_cmodule, MODULE_STRINGARG_ENABLED);
MP_REGISTER_MODULE(MP_QSTR_stringarg, stringarg_user_cmodule);

The macro defined in ``objstr.h`` takes three arguments, out of which
only the first one is actually defined. The other two are defined in the
Expand Down Expand Up @@ -271,13 +271,13 @@ https://github.com/v923z/micropython-usermod/tree/master/snippets/stringarg/micr
USERMODULES_DIR := $(USERMOD_DIR)

# Add all C files to SRC_USERMOD.
SRC_USERMOD += $(USERMODULES_DIR)/stringarg.c
SRC_USERMOD_C += $(USERMODULES_DIR)/stringarg.c

CFLAGS_USERMOD += -I$(USERMODULES_DIR)
.. code:: bash

!make clean
!make USER_C_MODULES=../../../usermod/snippets CFLAGS_EXTRA=-DMODULE_STRINGARG_ENABLED=1 all
!make USER_C_MODULES=../../../usermod/snippets/stringarg
.. code ::

%%micropython
Expand Down Expand Up @@ -380,7 +380,7 @@ https://github.com/v923z/micropython-usermod/tree/master/snippets/keywordfunctio
.globals = (mp_obj_dict_t*)&keywordfunction_module_globals,
};

MP_REGISTER_MODULE(MP_QSTR_keywordfunction, keywordfunction_user_cmodule, MODULE_KEYWORDFUNCTION_ENABLED);
MP_REGISTER_MODULE(MP_QSTR_keywordfunction, keywordfunction_user_cmodule);

One side effect of a function with keyword arguments is that we do not
have to care about the arguments in the C implementation: the argument
Expand Down Expand Up @@ -432,13 +432,13 @@ https://github.com/v923z/micropython-usermod/tree/master/snippets/keywordfunctio
USERMODULES_DIR := $(USERMOD_DIR)

# Add all C files to SRC_USERMOD.
SRC_USERMOD += $(USERMODULES_DIR)/keywordfunction.c
SRC_USERMOD_C += $(USERMODULES_DIR)/keywordfunction.c

CFLAGS_USERMOD += -I$(USERMODULES_DIR)
.. code:: bash

!make clean
!make USER_C_MODULES=../../../usermod/snippets CFLAGS_EXTRA=-DMODULE_KEYWORDFUNCTION_ENABLED=1 all
!make USER_C_MODULES=../../../usermod/snippets/keywordfunction
.. code ::

%%micropython
Expand Down Expand Up @@ -542,7 +542,7 @@ https://github.com/v923z/micropython-usermod/tree/master/snippets/arbitrarykeywo
.globals = (mp_obj_dict_t*)&arbitrarykeyword_module_globals,
};

MP_REGISTER_MODULE(MP_QSTR_arbitrarykeyword, arbitrarykeyword_user_cmodule, MODULE_ARBITRARYKEYWORD_ENABLED);
MP_REGISTER_MODULE(MP_QSTR_arbitrarykeyword, arbitrarykeyword_user_cmodule);

Before compiling the code, let us think a bit about what is going on
here. The first argument, ``a``, is straightforward: that is a
Expand Down Expand Up @@ -606,13 +606,13 @@ https://github.com/v923z/micropython-usermod/tree/master/snippets/arbitrarykeywo
USERMODULES_DIR := $(USERMOD_DIR)

# Add all C files to SRC_USERMOD.
SRC_USERMOD += $(USERMODULES_DIR)/arbitrarykeyword.c
SRC_USERMOD_C += $(USERMODULES_DIR)/arbitrarykeyword.c

CFLAGS_USERMOD += -I$(USERMODULES_DIR)
.. code:: bash

!make clean
!make USER_C_MODULES=../../../usermod/snippets CFLAGS_EXTRA=-DMODULE_ARBITRARYKEYWORD_ENABLED=1 all
!make USER_C_MODULES=../../../usermod/snippets/arbitrarykeyword
.. code ::

%%micropython
Expand Down
Loading