{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "31cd209d-39a4-4e0b-b34a-ced26db5b7d3",
   "metadata": {},
   "source": "# Microcontrollers"
  },
  {
   "cell_type": "markdown",
   "id": "3238b122",
   "metadata": {},
   "source": [
    "This guide walks you through the process of profiling a TensorFlow Lite model on an MCU device using the **eIQ AI Toolkit** MCU profiling feature.\n",
    "\n",
    "You'll Learn key **eIQ AI Toolkit** API endpoints relevant to model profiling\n",
    "\n",
    "*Note: The MCU profiling supports only TF Lite models. Other model formats require conversion to TF Lite.*\n",
    "\n",
    "*Note: This guide was developed and run using Python 3.11.*"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d78ee44b",
   "metadata": {},
   "source": [
    "This guide requires the eIQ AI Toolkit backend to be running.\n",
    "If you haven't set it up yet, please refer to the following tutorial:\n",
    "[eIQ AI Toolkit setup & launch](../tools/aiToolkit/installRun.ipynb)"
   ]
  },
  {
   "cell_type": "code",
   "id": "c4a3758e",
   "metadata": {},
   "source": [
    "import requests\n",
    "from pathlib import Path\n",
    "\n",
    "# Set your eIQ AI Toolkit url:\n",
    "AI_TOOLKIT_BACKEND_URL = \"http://localhost:8000\""
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "id": "d30392d2",
   "metadata": {},
   "source": [
    "## Model"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9237d741",
   "metadata": {},
   "source": [
    "If you already have a trained model ready, simply update the path to point to its location.\n",
    "If you don’t have a trained model yet, set the path to a location where the model should be saved.\n",
    "(See the following sections for instructions on how to download a sample model.)"
   ]
  },
  {
   "cell_type": "code",
   "id": "f1fd89c4",
   "metadata": {},
   "source": [
    "model_path = Path(\"your_model_path.tflite\")"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "id": "3d4c2740",
   "metadata": {},
   "source": [
    "Use the following command or script to download the example model:\n",
    "\n",
    "*Note: Skip this step if you already have your own model.*"
   ]
  },
  {
   "cell_type": "code",
   "id": "7e847d26",
   "metadata": {},
   "source": [
    "example_model_url = \"https://eiq.nxp.com/training-materials/_misc/models/mobilenet_v3-small_224_1.0_uint8.tflite\"\n",
    "\n",
    "with open(model_path, \"wb\") as f:\n",
    "    response = requests.get(\n",
    "        url=example_model_url\n",
    "    )\n",
    "    f.write(response.content)"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "id": "79408bb2",
   "metadata": {},
   "source": [
    "### Model info"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ab403991",
   "metadata": {},
   "source": [
    "MCU profiling requires profiling content in JSON format. The profiling content is generated on the MCU device using *ModelRunner* utility . Here's a sample JSON schema for MCU profiling:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "575d10ae",
   "metadata": {},
   "source": [
    "```json\n",
    "{\n",
    "    \"timing\": 75000,\n",
    "    \"ktensor_arena_size\": 1240,\n",
    "    \"inputs\": [\n",
    "        {\n",
    "            \"name\": \"input_name\",\n",
    "            \"scale\": 0,\n",
    "            \"zero_points\": 0,\n",
    "            \"datatype\": \"FLOAT32\",\n",
    "            \"shape\": [\n",
    "                1,\n",
    "                3,\n",
    "                3\n",
    "            ]\n",
    "        }\n",
    "    ],\n",
    "    \"outputs\": [\n",
    "        {\n",
    "            \"name\": \"output_name\",\n",
    "            \"scale\": 0,\n",
    "            \"zero_points\": 0,\n",
    "            \"datatype\": \"FLOAT32\",\n",
    "            \"shape\": [\n",
    "                1,\n",
    "                1\n",
    "            ]\n",
    "        }\n",
    "    ],\n",
    "    \"layer_count\": 8,\n",
    "    \"layers\": [\n",
    "        {\n",
    "            \"name\": \"layer_name\",\n",
    "            \"type\": \"layer_type\",\n",
    "            \"avg_timing\": 7000,\n",
    "            \"tensor\": {\n",
    "                \"timing\": 7000\n",
    "            }\n",
    "        }\n",
    "    ]\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6af2c516",
   "metadata": {},
   "source": [
    "To generate the JSON schema:\n",
    "\n",
    "1. [Flash the MCU](https://mcuxpresso.nxp.com/mcuxsdk/latest/html/middleware/eiq/tensorflow-lite/docs/topics/example_applications.html) with eIQ example `tflm_modelrunner`.\n",
    "2. With `tflm_modelrunner` example running on the MCU, follow the [example guide](https://mcuxpresso.nxp.com/mcuxsdk/latest/html/examples/eiq_examples/tflm_modelrunner/readme.html) to generate the *Model Info* JSON file."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ec6168d3",
   "metadata": {},
   "source": [
    "Save the Model Info JSON on your local machine and set the file path. Set arbitrary profiling run name:"
   ]
  },
  {
   "cell_type": "code",
   "id": "5aedd9ec",
   "metadata": {},
   "source": [
    "profiling_file_path=Path(\"model_info.json\")\n",
    "profiling_run_name=\"example_mcu_profiling_run\""
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "id": "2b331171",
   "metadata": {},
   "source": [
    "## Profiling"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a35a098a",
   "metadata": {},
   "source": "With the profiling content file invoke the eIQ AI Toolkit endpoint `/profiling/run_mcu_profiling`:"
  },
  {
   "cell_type": "code",
   "id": "42c22067",
   "metadata": {},
   "source": [
    "with open(profiling_file_path, \"rb\") as profiling_file:\n",
    "    response = requests.post(\n",
    "        url=f\"{AI_TOOLKIT_BACKEND_URL}/profiling/run_mcu_profiling\",\n",
    "        files = {\n",
    "            \"profiling_file\": (profiling_file_path.name, profiling_file, \"application/json\"),\n",
    "            \"name\": (None, profiling_run_name),\n",
    "        }\n",
    "    )\n",
    "\n",
    "data = response.json()\n",
    "print(data)\n",
    "profiling_uuid = data[\"data\"][\"profiling\"][\"uuid\"] # Assigned identifier of the requested profiling run"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "id": "2c4ad971",
   "metadata": {},
   "source": [
    "After initiating the profiling job, you can monitor its progress using the following API call:"
   ]
  },
  {
   "cell_type": "code",
   "id": "1ad6770a",
   "metadata": {},
   "source": [
    "response = requests.get(\n",
    "    url=f\"{AI_TOOLKIT_BACKEND_URL}/profiling/{profiling_uuid}\" # Profiling run identifier is part of the request URL\n",
    ")\n",
    "\n",
    "data = response.json()\n",
    "print(data)\n",
    "print(f'Profiling status: {data[\"data\"][\"profiling\"][\"status\"]}')\n",
    "print(f'Profiling status description: {data[\"data\"][\"profiling\"][\"status_description\"]}')"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "id": "c2b25313",
   "metadata": {},
   "source": [
    "Once the profiling status is marked as `success` you can proceed to analyze the results. If the status is still `in_progress`, re-run the status check (cell above) until the profiling completes."
   ]
  },
  {
   "cell_type": "code",
   "id": "abe5f415",
   "metadata": {},
   "source": [
    "profiling_data = data[\"data\"][\"profiling\"]\n",
    "print(profiling_data)"
   ],
   "outputs": [],
   "execution_count": null
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "sphinx-env (3.11.11)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}