Update pycardium guide

en/firmware/pycardium_modules.md

@@ -4,12 +4,52 @@ title: Pycardium Modules Development
 
 Pycardium is our micropython port.  You can find it [here](https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/pycardium).
 
-This page gives an overview on adding new C modules to pycardium.  These modules are mostly meant to make use of the [Epicardium API](./epicardium_api_development) to enable python scripts to interact with card10.
+This page gives an overview on adding new modules to pycardium.  There are two kinds of modules:
 
-## Basic Structure
+#### Modules written in Python
+Python modules are written in ... python.  They live in [`pycardium/modules/py`](https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/pycardium/modules/py) and are pre-compiled and packed into pycardium at build-time.  Python modules are meant to be used for creating abstractions and helpers based on lower level functionality.  The rationale is that it is easier to write pythonic modules in python instead of having to wrap all that in C code.  Though care has to be taken as these modules get quite big.
+
+
+#### Modules written in C
+C modules allow MicroPython code to interface with the rest of the system or allow a much faster implementation of performance-critical code.  For interfacing with card10, these modules are mostly meant to make use of the [Epicardium API](../epicardium_api_development).
+
+## Table Of Contents
+- [Python Modules](#python-modules)
+  - [Adding a new python module](#adding-a-new-python-module)
+  - [Size Considerations](#size-considerations)
+- [C Modules](#c-modules)
+  - [Basic Structure](#basic-structure)
+    - [Module Source](#module-source)
+    - [Build System](#build-system)
+    - [QSTR Definitions](#qstr-definitions)
+    - [Enable Module](#enable-module)
+  - [Wrapping Epicardium API](#wrapping-epicardium-api)
+  - [QSTR](#qstr)
+
+## Python Modules
+
+### Adding a new python module
+Add a file with the name of the module you want to [`pycardium/modules/py`](https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/pycardium/modules/py).  Make the build-system aware of the new python module by adding it in [`pycardium/modules/py/meson.build`](https://git.card10.badge.events.ccc.de/card10/firmware/blob/master/pycardium/modules/py/meson.build).  Rebuild and you should have your module available in MicroPython!  You can list the available modules in MicroPython using the following command:
+
+```python
+help("modules")
+```
+
+### Size Considerations
+Python modules can get quite big.  If you want to get a feeling for how big, take a look at
+
+```
+ls -lh build/pycardium/*@@frozen.c@*/
+```
+
+If your module needs a lookup table or other kind of big data-file, consider pushing that out into the external flash.  This is not yet possible, however (tracking [#11](https://git.card10.badge.events.ccc.de/card10/firmware/issues/11)).
+
+## C Modules
+
+### Basic Structure
 
 #### Module Source
-Modules live in [`pycardium/modules`](https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/pycardium/modules).  To add a new module, create a file in there containing the following example content.  This module is named `example` but you should of course replace that with your own name:
+C modules live in [`pycardium/modules`](https://git.card10.badge.events.ccc.de/card10/firmware/tree/master/pycardium/modules).  To add a new module, create a file in there containing the following example content.  This module is named `example` but you should of course replace that with your own name:
 ```c
 #include "py/obj.h"