Basic usage for Micro Controllers

Build and run an example model

At first, make sure the environment has been set up correctly already (refer to Environment requirement).

The followings are instructions about how to quickly build and run a provided model in MACE Model Zoo.

Here we use the har-cnn model as an example.

Commands

1. Pull MACE project.

git clone https://github.com/XiaoMi/mace.git
cd mace/
git fetch --all --tags --prune

# Checkout the latest tag (i.e. release version)
tag_name=`git describe --abbrev=0 --tags`
git checkout tags/${tag_name}

Note

It's highly recommended to use a release version instead of master branch.

2. Pull MACE Model Zoo project.

git clone https://github.com/XiaoMi/mace-models.git

3. Convert the pre-trained har-cnn model to c++ code.

cd path/to/mace
# output lib path: build/har-cnn/model/har_cnn_micro.tar.gz
CONF_FILE=/path/to/mace-models/micro-models/har-cnn/har-cnn.yml
python tools/converter.py convert --config=$CONF_FILE --enable_micro

4. Build Micro-Controllers engine and models to library on host.

# copy convert result to micro dir ``path/to/micro``
cp build/har-cnn/model/har_cnn_micro.tar.gz path/to/micro/
cd path/to/micro
tar zxvf har_cnn_micro.tar.gz
bazel build //micro/codegen:micro_engine

Note

• This step can be skipped if you just want to run a model using tools/python/run_micro.py, such as commands in step 5.
• The build result bazel-bin/micro/codegen/libmicro_engine.so's abi is host, if you want to run the model on micro controllers, you should build the code with the target abi.

5. Run the model on host.

CONF_FILE=/path/to/mace-models/micro-models/har-cnn/har-cnn.yml
# Run
python tools/python/run_micro.py --config $CONF_FILE --model_name har_cnn --build

# Test model run time
python tools/python/run_micro.py --config $CONF_FILE --model_name har_cnn --build --round=100

# Validate the correctness by comparing the results against the
# original model and framework, measured with cosine distance for similarity.
python tools/python/run_micro.py --config $CONF_FILE --model_name har_cnn --build --validate
# Validate the layers' correctness.
python tools/python/run_micro.py --config $CONF_FILE --model_name har_cnn --build --validate --layers 0:-1

Deploy your model into applications

Please refer to /mace/micro/tools/micro_run.cc for full usage. The following list the key steps.

// Include the headers
#include "micro/include/public/micro.h"

// 1. Create MaceMicroEngine instance
MaceMicroEngine *micro_engine = nullptr;
MaceStatus status = har_cnn::GetMicroEngineSingleton(&micro_engine);

// 1. Create and register Input buffers
std::vector<std::shared_ptr<char>> inputs;
std::vector<int32_t> input_sizes;
for (size_t i = 0; i < input_shapes.size(); ++i) {
  input_sizes.push_back(std::accumulate(input_shapes[i].begin(),
                                        input_shapes[i].end(), sizeof(float),
                                        std::multiplies<int32_t>()));
  inputs.push_back(std::shared_ptr<char>(new char[input_sizes[i]],
                                         std::default_delete<char[]>()));
}
// TODO: fill data into input buffers
for (size_t i = 0; i < input_names.size(); ++i) {
  micro_engine->RegisterInputData(i, inputs[i].get(),
                                  input_shapes[i].data());
}

// 3. Run the model
MaceStatus status = micro_engine->Run();

// 4. Get the results
for (size_t i = 0; i < output_names.size(); ++i) {
  void *output_buffer = nullptr;
  const int32_t *output_dims = nullptr;
  uint32_t dim_size = 0;
  MaceStatus status =
      micro_engine->GetOutputData(i, &output_buffer, &output_dims, &dim_size);
  // TODO: the result data is in output_buffer, you can not delete output_buffer.
}