Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/c272/micro-tools

A collection of tools to enhance the micro:bit v2 developer experience.
https://github.com/c272/micro-tools

codal microbit-v2

Last synced: about 2 months ago
JSON representation

A collection of tools to enhance the micro:bit v2 developer experience.

Awesome Lists containing this project

README 

        
# micro-tools License BadgePlatform Badge

*A collection of tools to enhance the micro:bit v2 developer experience.*



Welcome to the `micro-tools` repository, a collection of scripts and utilities which improve the quality of life experience for working with the CODAL micro:bit v2 API. There are several tools included in this repository, the most important ones being:



- `microinit`: Sets up a micro:bit v2 project directory for Visual Studio Code, configuring the include directories, compiler options and debug settings for the local CODAL API.

- `microbuild`: Allows for the easy building of micro:bit v2 projects anywhere in your filesystem, removing the need to place your code into the microbit-v2-samples source folder, as well as simple include injection into the CODAL build system.

- `microflash`: Facilitates the mounting, unmounting, and flashing of the micro:bit v2 in a distro-compatible way, removing the need to fiddle with manually mounting and copying to the micro:bit.



The tooling in this repository is aimed at **Linux** distributions and **MacOS** (tested on Apple Silicon), however does not require any heavy dependencies, so should work correctly on Windows under MinGW, however that is not guaranteed, and not a use case that this repository will support. These tools are all licensed under the GPLv3, so feel free to fork and contribute changes if you find something worth improving.



## Getting Started 

To get started using `micro-tools`, first clone the repository into a directory with user execute permissions.

```bash

git clone https://github.com/c272/micro-tools.git

cd micro-tools/

```



Once this is done, if you have **not** yet downloaded a local copy of the micro:bit v2 samples repository, you can simply run `microinstall.sh` to install and set up everything automatically. This will require either `apt`, `xbps-install` or `brew` to be installed.

```

./microinstall.sh

```



If this is not the case, and you already have a local copy of the samples repository, you can run `microinstall.sh` with the `DEPENDENCIES_ONLY` flag, and then run the `setup.sh` script found at the root of the repository to configure the location of your micro:bit v2 SDK (where your `microbit-v2-samples` repository is located).

```

./microinstall.sh DEPENDENCIES_ONLY=true

./setup.sh

```



Running the setup will create an `aliases.sh` file which defines command aliases for all the scripts contained within the repository. The output of the setup (through either method) should prompt you to source an alias script file upon completion. Place the provided command in your preferred terminal's `.****rc` file (such as `~/.bashrc`), like so:

```bash

...

source /path/to/micro-tools/aliases.sh

...

```



Now you're good to go! Start a new terminal instance, and you should be able to initialise projects with `microinit` and build with `microbuild`.



## Usage

### microinstall

This tool allows you to install the SDK from scratch, without having cloned anything else but this repository. After cloning this, you can simply run:

```

./microinstall.sh

```

And the SDK will be downloaded, installed, and configured to work with the rest of the tools & utilities in this suite. This only supports distributions with either the `apt` package manager (Debian, Ubuntu, Pop!_OS and other Debian-based), the `xbps-install` package manager (Void Linux), or `brew` (MacOS). This tool also isn't added as an alias, as you'll likely only want to use it once.



### microinit

This tool allows you to set up Visual Studio Code configurations for a micro:bit v2 project, to allow you to access the APIs with Visual Studio Code's code completion and Intellisense features without the need to be inside the `microbit-v2-samples` folder, as well as the ability to automatically run `microbuild` from within Visual Studio Code's interface. To start a new project with `microinit`, do the following:

```bash

microinit my-project-name

```



This will create a folder named "my-project-name", containing the appropriate VSCode configuration for your system.

Alternatively, if you already have a project directory, you can simply specify the directory name and it will perform setup there. For instance, to initialise in the current directory:

```bash

microinit .

```

Once this is done, you should be able to launch VSCode and see that include paths are properly resolved, and you can build with `microbuild` through Visual Studio Code's build system.



### microbuild

This tool allows for the building of micro:bit v2 projects outside of the `microbit-v2-samples` source folder. To build the default directory (found in `config.sh`, by default this is simply the current directory '`.`'), simply run:

```bash

microbuild

```



To specify a directory to build when running the command, you can add the argument `BUILD_DIRECTORY` with the desired folder. In addition, you can specify the output directory of the `MICROBIT.hex` file with the `BUILD_OUTPUT_DIRECTORY` argument. Most arguments in `micro-tools` are specified with a key-value format, like so:

```

microbuild BUILD_DIRECTORY=./src BUILD_OUTPUT_DIRECTORY=./bin

```

This would take `src` as the source project to build, and `bin` as the destination for the `MICROBIT.hex` file.



#### Includes with `.microbuild`

Along with simple builds, `microbuild` also supports injecting user-specified includes into the CODAL build system. For example, if you have a header only library such as `cereal`, you could add this to your C++ build very easily. To add additional include folders and files to your project, create a file named "`.microbuild`" in the root of your project. This should be in the folder specified by `BUILD_DIRECTORY` (usually `.`).



Inside this file, place all include directories and files you wish to include, one per line. You can also use wildcard formats to specify that all the files in a given directory should be added to the base include path. Here is an example:

```

deps/cereal/include

deps/EmbeddedProto/src/*

```



### microflash

This tool allows for the flashing of built micro:bit v2 projects to the micro:bit. By default, `microflash` will search for a file named `MICROBIT.hex` in the executing directory (this can be configured in `config.h` or passed in as the command line parameter `MICROBIT_HEX_FILE`), and flash this onto the microbit once mounted. You can perform this with simply:

```bash

microflash

```



The first time the micro:bit is flashed, it is mounted to a directory on the filesystem. By default, this is `mnt/microbit` within the scripts directory, however you can configure this directory in `config.sh` or pass it in as the command line option `MICROBIT_MOUNT_DIR`. If you want to just mount or unmount the micro:bit without performing a flash for whatever reason, you can simply pass the `DO_MOUNT` and `DO_UNMOUNT` arguments respectively to `microflash` like so:

```bash

microflash DO_UNMOUNT=true # Unmounts the micro:bit from the system, then exits.

microflash DO_MOUNT=true # Mounts the micro:bit to the mount directory, then exits.

```



### config.sh

There is a global configuration file "`config.sh`", which can be found at the root of the `micro-tools` directory which specifies default options for all of the utilities within `micro-tools`. It also defines the global location of the micro:bit v2 SDK (the `microbit-v2-samples` repository clone). If you wish to move the SDK somewhere else, you must let `micro-tools` know about the new location of the SDK, otherwise all utilities will stop working. You can do this by editing the global config value `MICROBIT_SDK_DIRECTORY`, like so:

```bash

####################

## Global Options ##

####################



# Location of the micro:bit v2 SDK (as cloned from microbit-v2-samples).

export MICROBIT_SDK_DIRECTORY=/path/to/my/microbit-v2-samples

...

```