caiman 0.1.0

A build system for MicroPython projects

caiman

A build system for MicroPython applications.

Features

• Define named targets for MicroPython sources, third party dependencies, and config resources
• Selectively tag targets for mpy compilation or freezing
• Dependency management using mip with dual install locations for development and deployment
• Maintains a build copy on your development machine for code completion
• Build code deployment to target devices using mpremote

Requirements

• Python 3.9+ for local development
• MicroPython installed and added to PATH on your local machine
• MicroPython installed on your target device

Installation

1. In your development environment, install caiman in a Python virtual environment:

   pip install caiman
   

2. Install a MicroPython port on your development machine.

   • If developing on a Mac, you can use brew:

   brew install micropython
   

3. Flash the MicroPython firmware on your target device.

Initialize a new project

• Installing caiman in your local Python environment will make the caiman command available.
• All caiman commands are run from the root of your project directory.
• caiman is configured using a caiman.yaml file in the root of your project.

Run the following command from the root of a new project directory:

caiman init

An interactive prompt will guide you through the setup process. At the end, a caiman.yaml file will be created in the root of your project, together with a basic directory structure.

Your project directory should look like this:

• caiman.yaml the project configuration file with your build targets and project metadata.
• build folder. Contains the build copy of your project, together with dependency artifacts and manifest files for your targets. Add this to .gitignore!
• venv/mip-packagesfolder which stores local copies of your mip installed dependencies for code completion. Add this to .gitignore and to your PYTHONPATH. This folder will be copied over to the build folder when the build command runs.
• venv/tools mip installed dependencies for development only. Not deployed to the device.
• micropython an example folder for your MicroPython source target. You can rename this folder from caiman.yaml or define additional source targets. Add this to PYTHONPATH for code completion.

Building your entire project

To build all targets in your project, run the following command from the root of your project:

caiman build

This will copy and selectively compile or freeze all targets defined in your caiman.yaml file to the build folder. Nothing is deployed on your device at this point.

The following sections will explain how to define your build targets.

Defining MicroPython sources

To define a MicroPython source target, add a new entry to your caiman.yaml file. A sample source was created in the micropython folder during project initialization.

sources:
- name: micropython # the name of the target
  parent: micropython # the parent directory of MicroPython sources
  frozen: false # whether to tag the target for freezing to firmware (separate firmware build required)
  compile: true # whether to compile the target to mpy
  files: # paths to component files relative to the parent directory
  - '**/*.py'
  version: '' # optional - version of the target

To build all source targets, run the following command from the root of your project:

caiman build --target=sources

This will copy matching source files from all source targets into the build/micropython folder. Sources tagged for compilation will be compiled to mpy format at this point.

Defining resources

Any files that are not MicroPython sources can be defined as resources. These can be config files, images, or other data files that your application needs.

To define a resource target, add a new entry to your caiman.yaml file in the resources section.

resources:
- name: resources # the name of the target
  parent: resources # the parent directory of resources

The above example will copy all files from the resources folder to the build/micropython folder.

To build all resource targets, run the following command from the root of your project:

caiman build --target=resources

Defining dependencies

A local install of MicroPython is required for dependency management. Make sure it's discoverable on the PATH

Dependencies are managed using mip, a MicroPython package manager. They are specified in the caiman.yaml file in the dependencies section.

Example:

dependencies:
- name: logging
  version: latest
  frozen: false # whether to tag the target for freezing to firmware (separate firmware build required)
  compile: true # whether to compile the target to mpy. Local install is always not compiled.

This example will install the logging package from the MicroPython package index.

To install all dependencies, run the following command from the root of your project:

caiman build --target=dependencies

You can also define specific files that you want to fetch from a dependency.

Example:

dependencies:
  - name: github:T0ha/uprotobuf
    version: main
    files:
      - protobuf/uprotobuf.py

This will only install the specified files from the uprotobuf github repository.

Defining tools

Tools are dependencies that are only required for development and are not deployed to the device. They are specified in the caiman.yaml file in the tools section. You can use parts of a dependency for development only by specifying the files you need.

Example:

tools:
  - name: github:T0ha/uprotobuf
    version: main
    compile: false
    files:
      - scripts/uprotobuf_plugin.py

Building all tools:

caiman build --target=tools

This command will copy the specified files from the dependency to the venv/tools folder.

Deploying to the device

Ensure your device is connected via USB and is discoverable: ls -latr /dev | grep tty.usbmodem on OSX.

Ensure no other processes are using the serial port when deploying to the device. This includes any IDE plugins.

The deployment operation copies the contents of build/micropython to the target device.

To deploy all targets, run the following command from the root of your project:

caiman deploy

Device Operations

List files on the device

caiman walk --target=/

Remove all files from the device

WARNING: This will remove all files from the device!

caiman rmtree --target=/

Dump file contents to the console

caiman cat --target=/boot.py

To do this without logging (useful for parsing):

caiman --silent cat --target=/boot.py

Run a file on the device

caiman run --target=boot