tutorial-key.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "hideCode": false,
    "hidePrompt": false
   },
   "source": [
    "\n",
    "# Quick Start\n",
    "----\n",
    "\n",
    "**dSpace makes it easy to build simple, declarative, and composable abstractions in smart spaces.**\n",
    "\n",
    "Define a digi schema:\n",
    "```yaml\n",
    "group: digi.dev\n",
    "version: v1\n",
    "kind: Plug\n",
    "control:\n",
    "  power: string\n",
    "``` \n",
    "\n",
    "Program the digi's driver:\n",
    "```python\n",
    "from digi import on\n",
    "\n",
    "# tuya device library\n",
    "import pytuya\n",
    "plug = pytuya.Plug(\"DEVICE_ID\")\n",
    "\n",
    "@on.control(\"power\")\n",
    "def h(power):\n",
    "    plug.set(power[\"intent\"])\n",
    "```\n",
    "\n",
    "Build and run the digi:\n",
    "```bash\n",
    "dq build plug; dq run plug plut-test\n",
    "```\n",
    "\n",
    "Update the intent of the digi in the model:\n",
    "```yaml\n",
    "apiVersion: digi.dev/v1\n",
    "kind: Plug        \n",
    "metadata:\n",
    "  name: plug-test\n",
    "spec:\n",
    "  control:        \n",
    "    power:\n",
    "      # 'I want the plug switched off'\n",
    "      intent: \"off\"\n",
    "```\n",
    "\n",
    "And apply the it via kubectl:\n",
    "`kubectl apply -f MODEL_YAML`\n",
    "\n",
    "\n",
    "\n",
    "## Concepts\n",
    "----\n",
    "\n",
    "**Digi:** The basic building block in dSpace is called _digi_. Each digi has a _model_ and a _driver_. A model consists of attribute-value pairs organized in a document (JSON) following a predefined _schema_. The model describes the desired and the current states of the digi; and the goal of the digi's driver is to take actions that reconcile the current states to the desired states. \n",
    "\n",
    "**Programming driver:** Each digi's driver can only access its own model (think of it as the digi's \"world view\"). Programming a digi is conceptually very simple - manipulating the digi's model/world view (essentially a JSON document) plus any other actions to affect the external world (e.g., send a signal to a physical plug, invoke a web API, send a text messages to your phone etc.). The dSpace's runtime will handle the rest, e.g., syncing states between digis' world views when they are composed.\n",
    "\n",
    "**Build and run:** After defining the digi's schema and programing its driver, developers can build a _digi image_ and push it to a digi repository for distributiton. Users can then pull the digi image, run it on dSpace, and interact with the digi by updating its model, e.g., specifies its desired states. \n",
    "\n",
    "**Digivice:** In this tutorial, we will focus on a special type of digi called _digivice_ (e.g., the Plug in Quick Start). A digivice model has control attributes (e.g., `control.power` in Plug) where each control attribute has an intent field (tracking the desired states) and a status field (tracking the current states). \n",
    "\n",
    "Digivices can be composed via the _mount_ operator, forming digivice hierarchies.  Mounting a digi A to another digi B will allow B to change the intent fields and read the status fields of A (via updating the corresponding attribute replica of A in B's own model).\n",
    "\n",
    "## How to use this notebook\n",
    "----\n",
    "\n",
    "This notebook contains a tutorial on building abstractions for a simple home smart space. You will run through each notebook cell serially. Make sure every cell before it has been run successfully before running the current cell. \n",
    "\n",
    "To run a notebook cell, you can click the `Run` button in the panel (or hit `shift + ENTER` as a shortcut). When a cell is run, its outputs will appear on the cell's output section. \n",
    "\n",
    "> Note: the notebook contains a few macros (e.g., `%elapsed_time`, `%%writefile`); you should be able to safely ignore them. Commands with a leading macro `!` are ones will be executed in shell."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Home space\n",
    "----\n",
    "\n",
    "In this tutorial, we will learn how to implement a simple declarative space for home in dSpace. \n",
    "\n",
    "This example space includes `lamps`, `rooms`, `motion sensors`, and the `home`. We will compose these abstractions and define policies and automations. \n",
    "\n",
    "**We left a few lines of code and configurations to fill. They are marked by `YOUR CODE HERE`.** The tutorial should take about 15-30 min to walk through. \n",
    "\n",
    "## Setup and tools\n",
    "----\n",
    "We will be using two command line tools:\n",
    "\n",
    "* **dq**: dSpace's CLI; used to build a digi-image (`dq build`), run a digi (`dq run`), and compose digivices (`dq mount CHILD PARENT`).\n",
    "* **kubectl**: Kubernetes's CLI; used to update and check digi's states. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0:00:00\n"
     ]
    }
   ],
   "source": [
    "from tutorial import (\n",
    "    create,\n",
    "    model_file,\n",
    "    handler_file,\n",
    ")\n",
    "%elapsed_time"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Lamp digivice\n",
    "----\n",
    "\n",
    "This simple lamp digivice allows one to configure its power (\"on\" or \"off\") and brightness level."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Define a schema"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0:00:02\n"
     ]
    }
   ],
   "source": [
    "%%elapsed_time\n",
    "\n",
    "schema = \"\"\"\n",
    "group: digi.dev\n",
    "version: v1\n",
    "kind: Lamp\n",
    "control:\n",
    "  power: string  \n",
    "  # Add a 'brightness' attribute to the lamps's \n",
    "  # schema. The following data types are allowed: \n",
    "  # {number, integer, string, array,object}\n",
    "  # YOUR CODE HERE\n",
    "  brightness: number\n",
    "\"\"\"\n",
    "\n",
    "create(schema)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Define a model"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "m = model_file(\"lamp\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Writing /Users/silv/go/src/digi.dev/tutorial/workdir/lamp/deploy/cr.yaml\n",
      "0:00:05\n"
     ]
    }
   ],
   "source": [
    "%%elapsed_time\n",
    "%%writefile $m\n",
    "\n",
    "apiVersion: digi.dev/v1\n",
    "kind: Lamp         \n",
    "metadata:\n",
    "  name: {{ .Values.name }}\n",
    "spec:\n",
    "  control:        \n",
    "    power:\n",
    "      intent: \"on\"\n",
    "    brightness:\n",
    "      intent: 0.8"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Implement a driver\n",
    "----\n",
    "**Goal:** Implement a \"mock\" driver that simply sets the lamp's status equal to its intent."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "f = handler_file(\"lamp\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting /Users/silv/go/src/digi.dev/tutorial/workdir/lamp/driver/handler.py\n",
      "0:00:07\n"
     ]
    }
   ],
   "source": [
    "%%elapsed_time\n",
    "%%writefile $f\n",
    "\n",
    "from digi import on\n",
    "\n",
    "@on.control(\"power\")\n",
    "def handle_power(sv):\n",
    "    # sv (shorthand for \"subview\") gives acess\n",
    "    # to the sub-tree of the lamp's model rooted\n",
    "    # at the \"power\" attribute\n",
    "    sv[\"status\"] = sv[\"intent\"]\n",
    "\n",
    "@on.control(\"brightness\")\n",
    "def handle_brightness(sv):\n",
    "    # set the status of brightness\n",
    "    # YOUR CODE HERE\n",
    "    sv[\"status\"] = sv[\"intent\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Build"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "IMAGE ID\r\n",
      "lamp\r\n",
      "motionsensor\r\n",
      "room\r\n"
     ]
    }
   ],
   "source": [
    "!dq build lamp -q  # quiet\n",
    "!dq image"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Run"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "lamp-test\r\n"
     ]
    }
   ],
   "source": [
    "!dq run lamp lamp-test\n",
    "# !dq stop lamp lamp-test"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Read status"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "apiVersion: digi.dev/v1\r\n",
      "kind: Lamp\r\n",
      "metadata:\r\n",
      "  name: lamp-test\r\n",
      "  namespace: default\r\n",
      "spec:\r\n",
      "  control:\r\n",
      "    brightness:\r\n",
      "      intent: 0.8\r\n",
      "      status: 0.8\r\n",
      "    power:\r\n",
      "      intent: \"on\"\r\n",
      "      status: \"on\"\r\n"
     ]
    }
   ],
   "source": [
    "!kubectl get lamp.digi.dev lamp-test -oyaml | kubectl neat"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Update intent\n",
    "\n",
    "One can modify the intent field of control attributes to update the desired states of the digivice. Here, let's update the desired brightness to 0.1 (previously 0.8)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "m = model_file(\"lamp\", new=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting /Users/silv/go/src/digi.dev/tutorial/workdir/lamp/deploy/cr_run.yaml\n",
      "0:02:19\n"
     ]
    }
   ],
   "source": [
    "%%elapsed_time\n",
    "%%writefile $m\n",
    "\n",
    "apiVersion: digi.dev/v1\n",
    "kind: Lamp         \n",
    "metadata:\n",
    "  name: lamp-test\n",
    "spec:\n",
    "  control:        \n",
    "    power:\n",
    "      intent: \"on\"\n",
    "    brightness:\n",
    "      intent: 0.1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "lamp.digi.dev/lamp-test configured\n",
      "apiVersion: digi.dev/v1\n",
      "kind: Lamp\n",
      "metadata:\n",
      "  name: lamp-test\n",
      "  namespace: default\n",
      "spec:\n",
      "  control:\n",
      "    brightness:\n",
      "      intent: 0.1\n",
      "      status: 0.1\n",
      "    power:\n",
      "      intent: \"on\"\n",
      "      status: \"on\"\n"
     ]
    }
   ],
   "source": [
    "!kubectl apply -f $m 2> /dev/null  \n",
    "!kubectl get lamp lamp-test -oyaml | kubectl neat"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "lamp.digi.dev/lamp-test patched (no change)\r\n"
     ]
    }
   ],
   "source": [
    "# Alternatively, one can patch using a string (the previous method is preferred!), e.g.,\n",
    "!kubectl patch lamp lamp-test -p '{\"spec\":{\"control\":{\"power\":{\"intent\":\"on\"}}}}' --type=merge"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# HL abstraction: Room digivice\n",
    "----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Schema and model"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0:02:26\n"
     ]
    }
   ],
   "source": [
    "%%elapsed_time\n",
    "\n",
    "# define schema\n",
    "schema = \"\"\"\n",
    "group: digi.dev\n",
    "version: v1\n",
    "kind: Room\n",
    "control:\n",
    "  brightness: number\n",
    "mount:     \n",
    "  digi.dev/v1/lamps: object\n",
    "  # ... additional digis\n",
    "\"\"\"\n",
    "\n",
    "create(schema)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "# specify model\n",
    "m = model_file(\"room\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Writing /Users/silv/go/src/digi.dev/tutorial/workdir/room/deploy/cr.yaml\n",
      "0:02:29\n"
     ]
    }
   ],
   "source": [
    "%%elapsed_time\n",
    "%%writefile $m\n",
    "\n",
    "apiVersion: digi.dev/v1\n",
    "kind: Room        \n",
    "metadata:\n",
    "  name: {{ .Values.name }}\n",
    "spec:\n",
    "  control:        \n",
    "    brightness:\n",
    "      intent: 0.8"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Implement a driver\n",
    "----\n",
    "**Goal:** The room digivice aggregates the brightness of all lamps mounted to it. This means:\n",
    "* The `control.brightness.status` should be equal to the sum of the corresponding `status` attribute of the lamps that are currently active (i.e., `power.intent == \"on\"`)\n",
    "* The value of `control.brightness.intent` should be divided across all lamps\n",
    "\n",
    "For example, given a room that has 10 lamps, if the room's `control.brightness.intent` is set to 1.0 and 5 of the lamps have `control.power.status == \"on\"`, then each of these active lamp's `control.brightness.intent` should be set to 1.0/5 = `0.2`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "f = handler_file(\"room\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting /Users/silv/go/src/digi.dev/tutorial/workdir/room/driver/handler.py\n",
      "0:02:32\n"
     ]
    }
   ],
   "source": [
    "%%elapsed_time\n",
    "%%writefile $f\n",
    "\n",
    "from digi import on\n",
    "from digi.view import TypeView, DotView\n",
    "\n",
    "@on.mount\n",
    "@on.control\n",
    "def handle_brightness(proc_view):    \n",
    "    with TypeView(proc_view) as tv, DotView(tv) as dv:  \n",
    "        # reference to room's brightness attribute;\n",
    "        # it contains two sub-fields .intent and .status\n",
    "        room_brightness = dv.root.control.brightness        \n",
    "        room_brightness.status = 0\n",
    "        \n",
    "        if \"lamps\" not in dv:\n",
    "            return\n",
    "\n",
    "        active_lamps = [l for _, l in dv.lamps.items() \n",
    "                        if l.control.power.status == \"on\"]\n",
    "        for lamp in active_lamps:\n",
    "            room_brightness.status += lamp.control.brightness.status \n",
    "            \n",
    "            # update lamp's intent\n",
    "            # YOUR CODE HERE\n",
    "            lamp.control.brightness.intent = room_brightness.intent / len(active_lamps) "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "room-test\r\n"
     ]
    }
   ],
   "source": [
    "# build and run\n",
    "!dq build room -q\n",
    "!dq run room room-test"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Debug\n",
    "----\n",
    "\n",
    "To add additional debug info:\n",
    "\n",
    "```python\n",
    "from digi import logger\n",
    "@control\n",
    "def h(proc_view):\n",
    "    logger.info(\"...\")\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "apiVersion: digi.dev/v1\r\n",
      "kind: Room\r\n",
      "metadata:\r\n",
      "  name: room-test\r\n",
      "  namespace: default\r\n",
      "spec:\r\n",
      "  control:\r\n",
      "    brightness:\r\n",
      "      intent: 0.8\r\n"
     ]
    }
   ],
   "source": [
    "!kubectl get rooms room-test -oyaml | kubectl neat"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[2021-04-25 23:10:14,300] digi                 [INFO    ] Started an operator\r\n",
      "[2021-04-25 23:10:14,300] digi.mount           [INFO    ] Started the mounter\r\n",
      "[2021-04-25 23:10:14,300] digi.mount           [INFO    ] Started the mounter\r\n",
      "[2021-04-25 23:10:14,304] kopf.reactor.running [WARNING ] OS signals are ignored: running not in the main thread.\r\n",
      "[2021-04-25 23:10:14,304] digi                 [INFO    ] Started an operator\r\n",
      "[2021-04-25 23:10:14,304] digi                 [INFO    ] Started an operator\r\n",
      "[2021-04-25 23:10:14,305] kopf.reactor.running [WARNING ] OS signals are ignored: running not in the main thread.\r\n",
      "[2021-04-25 23:10:14,616] digi.main            [INFO    ] Done reconciliation\r\n",
      "[2021-04-25 23:10:14,616] digi.main            [INFO    ] Done reconciliation\r\n",
      "[2021-04-25 23:10:14,728] digi.main            [INFO    ] Skipping gen 2\r\n",
      "[2021-04-25 23:10:14,728] digi.main            [INFO    ] Skipping gen 2\r\n"
     ]
    }
   ],
   "source": [
    "!dq log room-test"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Mount lamps"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "!dq mount lamp-test room-test"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "apiVersion: digi.dev/v1\r\n",
      "kind: Room\r\n",
      "metadata:\r\n",
      "  name: room-test\r\n",
      "  namespace: default\r\n",
      "spec:\r\n",
      "  control:\r\n",
      "    brightness:\r\n",
      "      intent: 0.8\r\n",
      "      status: 0.8\r\n",
      "  mount:\r\n",
      "    digi.dev/v1/lamps:\r\n",
      "      default/lamp-test:\r\n",
      "        mode: hide\r\n",
      "        spec:\r\n",
      "          control:\r\n",
      "            brightness:\r\n",
      "              intent: 0.8\r\n",
      "              status: 0.8\r\n",
      "            power:\r\n",
      "              intent: \"on\"\r\n",
      "              status: \"on\"\r\n",
      "        status: active\r\n"
     ]
    }
   ],
   "source": [
    "!kubectl get rooms room-test -oyaml | kubectl neat"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "lamp-test-2\r\n"
     ]
    }
   ],
   "source": [
    "# start a new lamp-test-2\n",
    "!dq run lamp lamp-test-2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [],
   "source": [
    "!dq mount lamp-test-2 room-test"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "apiVersion: digi.dev/v1\r\n",
      "kind: Room\r\n",
      "metadata:\r\n",
      "  name: room-test\r\n",
      "  namespace: default\r\n",
      "spec:\r\n",
      "  control:\r\n",
      "    brightness:\r\n",
      "      intent: 0.8\r\n",
      "      status: 0.8\r\n",
      "  mount:\r\n",
      "    digi.dev/v1/lamps:\r\n",
      "      default/lamp-test:\r\n",
      "        mode: hide\r\n",
      "        spec:\r\n",
      "          control:\r\n",
      "            brightness:\r\n",
      "              intent: 0.4\r\n",
      "              status: 0.4\r\n",
      "            power:\r\n",
      "              intent: \"on\"\r\n",
      "              status: \"on\"\r\n",
      "        status: active\r\n",
      "      default/lamp-test-2:\r\n",
      "        mode: hide\r\n",
      "        spec:\r\n",
      "          control:\r\n",
      "            brightness:\r\n",
      "              intent: 0.4\r\n",
      "              status: 0.4\r\n",
      "            power:\r\n",
      "              intent: \"on\"\r\n",
      "              status: \"on\"\r\n",
      "        status: active\r\n"
     ]
    }
   ],
   "source": [
    "!kubectl get rooms room-test -oyaml | kubectl neat"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or [watch the changes](http://localhost:8881/notebooks/display.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Playing with room brightness"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "room.digi.dev/room-test patched\r\n"
     ]
    }
   ],
   "source": [
    "!kubectl patch room room-test -p '{\"spec\":{\"control\":{\"brightness\":{\"intent\":1}}}}' --type=merge"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "apiVersion: digi.dev/v1\r\n",
      "kind: Room\r\n",
      "metadata:\r\n",
      "  name: room-test\r\n",
      "  namespace: default\r\n",
      "spec:\r\n",
      "  control:\r\n",
      "    brightness:\r\n",
      "      intent: 1\r\n",
      "      status: 1\r\n",
      "  mount:\r\n",
      "    digi.dev/v1/lamps:\r\n",
      "      default/lamp-test:\r\n",
      "        mode: hide\r\n",
      "        spec:\r\n",
      "          control:\r\n",
      "            brightness:\r\n",
      "              intent: 0.5\r\n",
      "              status: 0.5\r\n",
      "            power:\r\n",
      "              intent: \"on\"\r\n",
      "              status: \"on\"\r\n",
      "        status: active\r\n",
      "      default/lamp-test-2:\r\n",
      "        mode: hide\r\n",
      "        spec:\r\n",
      "          control:\r\n",
      "            brightness:\r\n",
      "              intent: 0.5\r\n",
      "              status: 0.5\r\n",
      "            power:\r\n",
      "              intent: \"on\"\r\n",
      "              status: \"on\"\r\n",
      "        status: active\r\n"
     ]
    }
   ],
   "source": [
    "!kubectl get rooms room-test -oyaml | kubectl neat"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Connect to physical lamps"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Activate the Room with motion\n",
    "----\n",
    "**Goal:** Allow the room to detect motion and adjust the brightness level accordingly. \n",
    "\n",
    "We will use a mock motion sensor (`mock.digi.dev/v1/motionsensors`) which \"pretends to detect\" motion event randomly over time. \n",
    "* When a motion is detected, the motion sensor updates its `obs.last_triggered_time` to the current time\n",
    "* The motion sensor has a `sensitivity` control attribute that decides how often the motion is generated"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Pull the MotionSensor"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "motionsensor\n",
      "motion-test\n"
     ]
    }
   ],
   "source": [
    "!dq pull motionsensor\n",
    "!dq run motionsensor motion-test"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "apiVersion: mock.digi.dev/v1\r\n",
      "kind: MotionSensor\r\n",
      "metadata:\r\n",
      "  name: motion-test\r\n",
      "  namespace: default\r\n",
      "spec:\r\n",
      "  control:\r\n",
      "    sensitivity:\r\n",
      "      intent: 1\r\n",
      "      status: 1\r\n",
      "  obs:\r\n",
      "    battery_level: 100%\r\n"
     ]
    }
   ],
   "source": [
    "!kubectl get motionsensor motion-test -oyaml | kubectl neat"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "motionsensor.mock.digi.dev/motion-test patched\r\n"
     ]
    }
   ],
   "source": [
    "# update the sensor's sensitivity (default to 1) \n",
    "# s.t. it generates events 10 times more often\n",
    "!kubectl patch motionsensor motion-test -p '{\"spec\":{\"control\":{\"sensitivity\":{\"intent\":10}}}}' --type=merge"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "apiVersion: mock.digi.dev/v1\r\n",
      "kind: MotionSensor\r\n",
      "metadata:\r\n",
      "  name: motion-test\r\n",
      "  namespace: default\r\n",
      "spec:\r\n",
      "  control:\r\n",
      "    sensitivity:\r\n",
      "      intent: 10\r\n",
      "      status: 10\r\n",
      "  obs:\r\n",
      "    battery_level: 100%\r\n",
      "    last_triggered_time: 1.619392494784037e+09\r\n"
     ]
    }
   ],
   "source": [
    "!kubectl get motionsensor motion-test -oyaml | kubectl neat"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Modify Room"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [],
   "source": [
    "schema = \"\"\"\n",
    "group: digi.dev\n",
    "version: v1\n",
    "kind: Room\n",
    "control:\n",
    "  brightness: number\n",
    "mount:     \n",
    "  digi.dev/v1/lamps: object\n",
    "  # allow Room to mount the motion sensor\n",
    "  mock.digi.dev/v1/motionsensors: object\n",
    "reflex: object\n",
    "\"\"\"\n",
    "\n",
    "create(schema, new=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "room-test\r\n"
     ]
    }
   ],
   "source": [
    "# build and run\n",
    "!dq build room -q\n",
    "!dq run room room-test"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Mount a motionsensor"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [],
   "source": [
    "!dq mount motion-test room-test"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [],
   "source": [
    "!dq mount lamp-test room-test"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [],
   "source": [
    "!dq mount lamp-test-2 room-test"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "apiVersion: digi.dev/v1\r\n",
      "kind: Room\r\n",
      "metadata:\r\n",
      "  name: room-test\r\n",
      "  namespace: default\r\n",
      "spec:\r\n",
      "  control:\r\n",
      "    brightness:\r\n",
      "      intent: 0.8\r\n",
      "      status: 0.8\r\n",
      "  mount:\r\n",
      "    digi.dev/v1/lamps:\r\n",
      "      default/lamp-test:\r\n",
      "        mode: hide\r\n",
      "        spec:\r\n",
      "          control:\r\n",
      "            brightness:\r\n",
      "              intent: 0.4\r\n",
      "              status: 0.4\r\n",
      "            power:\r\n",
      "              intent: \"on\"\r\n",
      "              status: \"on\"\r\n",
      "        status: active\r\n",
      "      default/lamp-test-2:\r\n",
      "        mode: hide\r\n",
      "        spec:\r\n",
      "          control:\r\n",
      "            brightness:\r\n",
      "              intent: 0.4\r\n",
      "              status: 0.4\r\n",
      "            power:\r\n",
      "              intent: \"on\"\r\n",
      "              status: \"on\"\r\n",
      "        status: active\r\n",
      "    mock.digi.dev/v1/motionsensors:\r\n",
      "      default/motion-test:\r\n",
      "        mode: hide\r\n",
      "        spec:\r\n",
      "          control:\r\n",
      "            sensitivity:\r\n",
      "              intent: 10\r\n",
      "              status: 10\r\n",
      "          obs:\r\n",
      "            battery_level: 100%\r\n",
      "            last_triggered_time: 1.6193925240519307e+09\r\n",
      "        status: active\r\n"
     ]
    }
   ],
   "source": [
    "!kubectl get room room-test -oyaml | kubectl neat"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Add Reflex\n",
    "----\n",
    "\n",
    "A reflex defines a policy/logic on the model itself. It allows users to augment or modify the behaviors of a digi at runtime without restarting or rebuilding it. \n",
    "\n",
    "A reflex has three attribtes: `policy` defines the logic in a processor specific language (e.g., jq - a popular JSON processor); `priority` defines which priority level this policy will run at (handlers in the driver have default priority of 0; a negative priority means the reflex is disabled); the `processor` defines which processor will be used. \n",
    "\n",
    "Each logic has a name which is its root attribute. One can use the reflex to reconfigure an existing handler's logic and priority too, by simply use that handler's name as the reflex's name.\n",
    "\n",
    "In the following example, we are going to add a reflex that updates room's brightness when there is motion."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {},
   "outputs": [],
   "source": [
    "# specify model\n",
    "m = model_file(\"room\", new=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting /Users/silv/go/src/digi.dev/tutorial/workdir/room/deploy/cr_run.yaml\n",
      "0:07:59\n"
     ]
    }
   ],
   "source": [
    "%%elapsed_time\n",
    "%%writefile $m\n",
    "\n",
    "apiVersion: digi.dev/v1\n",
    "kind: Room\n",
    "metadata:\n",
    "  name: room-test\n",
    "spec:\n",
    "  control:\n",
    "    brightness:\n",
    "      intent: 0.8\n",
    "  reflex:\n",
    "    motion-mode:  \n",
    "      # if the motion is detected recently (less than 10 minutes),\n",
    "      # set the room's brightness to 1\n",
    "      # YOUR CODE HERE \n",
    "      # Hint: fill in the missing (???) attributes\n",
    "      policy: >- # \n",
    "            if $time - .\"motion-test\".obs.last_triggered_time <= 600 \n",
    "            then .root.control.brightness.intent = 1 else . end  \n",
    "      priority: 0\n",
    "      processor: jq"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "room.digi.dev/room-test configured\r\n"
     ]
    }
   ],
   "source": [
    "!kubectl apply -f $m 2> /dev/null  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 51,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "apiVersion: digi.dev/v1\r\n",
      "kind: Room\r\n",
      "metadata:\r\n",
      "  name: room-test\r\n",
      "  namespace: default\r\n",
      "spec:\r\n",
      "  control:\r\n",
      "    brightness:\r\n",
      "      intent: 1\r\n",
      "      status: 1\r\n",
      "  mount:\r\n",
      "    digi.dev/v1/lamps:\r\n",
      "      default/lamp-test:\r\n",
      "        mode: hide\r\n",
      "        spec:\r\n",
      "          control:\r\n",
      "            brightness:\r\n",
      "              intent: 0.5\r\n",
      "              status: 0.5\r\n",
      "            power:\r\n",
      "              intent: \"on\"\r\n",
      "              status: \"on\"\r\n",
      "        status: active\r\n",
      "      default/lamp-test-2:\r\n",
      "        mode: hide\r\n",
      "        spec:\r\n",
      "          control:\r\n",
      "            brightness:\r\n",
      "              intent: 0.5\r\n",
      "              status: 0.5\r\n",
      "            power:\r\n",
      "              intent: \"on\"\r\n",
      "              status: \"on\"\r\n",
      "        status: active\r\n",
      "    mock.digi.dev/v1/motionsensors:\r\n",
      "      default/motion-test:\r\n",
      "        mode: hide\r\n",
      "        spec:\r\n",
      "          control:\r\n",
      "            sensitivity:\r\n",
      "              intent: 10\r\n",
      "              status: 10\r\n",
      "          obs:\r\n",
      "            battery_level: 100%\r\n",
      "            last_triggered_time: 1.6193925461424692e+09\r\n",
      "        status: active\r\n",
      "  reflex:\r\n",
      "    motion-mode:\r\n",
      "      policy: 'if $time - .\"motion-test\".obs.last_triggered_time <= 600  then .root.control.brightness.intent\r\n",
      "        = 1 else . end  '\r\n",
      "      priority: 0\r\n",
      "      processor: jq\r\n"
     ]
    }
   ],
   "source": [
    "!kubectl get room room-test -oyaml | kubectl neat"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Connect to real motion detectors"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Post tutorial question\n",
    "> Which part did you find most difficult?\n",
    "\n",
    "> Any suggestions on the programming/tools? "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Home (Bonus)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Pull the base image"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!dq pull home"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Modify the Home driver\n",
    "----\n",
    "**Goal:** Home have a \"mode\" control attribute that allows one to tune it to predefined modes. Each mode decides the brightness of the Rooms that mounted to the Home."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "f = handler_file(\"home\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%elapsed_time\n",
    "%%writefile $f\n",
    "\n",
    "# TBD\n",
    "import digi\n",
    "import digi.on as on\n",
    "\n",
    "# validation\n",
    "@on.attr\n",
    "def h():\n",
    "    ...\n",
    "\n",
    "# intent back-prop\n",
    "@on.mount\n",
    "def h():\n",
    "    ...\n",
    "\n",
    "# status\n",
    "@on.mount\n",
    "def h():\n",
    "    ...\n",
    "\n",
    "# intent\n",
    "@on.mount\n",
    "@on.control\n",
    "def h():\n",
    "    ..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# build and run\n",
    "!dq build home -q\n",
    "!dq run home home-test"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Mount rooms"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!dq mount room-test home-test"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# set the modes\n",
    "!kubectl patch home home-test -p '{\"spec\":{\"control\":{\"mode\":{\"intent\":YOURMODE}}}}' --type=merge"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.8.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}