State Machines in Python - Part 2.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# State Machines in Python - Part 2\n",
    "\n",
    "In this part, we have a closer look at a (simple) user interface to control our state machine, and discover more features of STMPY.\n",
    "\n",
    "\n",
    "### Installation and Setup\n",
    "\n",
    "If you run this notebook on Binder, all should work and you can jump to the next step.\n",
    "\n",
    "For the user interface to work in notebooks, you need to install ipywidgets:\n",
    "\n",
    "    python3 -m pip install ipywidgets\n",
    "    \n",
    "Then you need to enable them:\n",
    "\n",
    "    jupyter nbextension enable --py widgetsnbextension\n",
    "    \n",
    "You can also run the following cell, which executes these commands:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!python3 -m pip install ipywidgets\n",
    "!jupyter nbextension enable --py widgetsnbextension"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After the installation, run the following cell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from stmpy import Machine, Driver\n",
    "\n",
    "import ipywidgets as widgets\n",
    "from IPython.display import display"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Signal Light\n",
    "\n",
    "We create a blinking light. shown in the state machine below. \n",
    "\n",
    "![](images/signal-light.png)\n",
    "\n",
    "\n",
    "As basis, we use the code below that offers a simple user interface in Python Notebooks. It displays an image and two buttons. In addition, it prepares the action we need for the state machine. You don't need to understand all the details of it yet, but make sure you read all comments and understand what the different methods achieve."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class SignalLight:\n",
    "\n",
    "    # callback method, called by the button 'switch' when it is pressed\n",
    "    def on_button_switch(self, b):\n",
    "        self.stm.send('switch')  # <---- here we send a signal\n",
    "\n",
    "    # callback method, called by the button 'terminate' when it is pressed\n",
    "    def on_button_terminate(self, b):\n",
    "        self.stm.driver.stop()  # <---- here we stop the driver\n",
    "\n",
    "    # called by the initial transition\n",
    "    def __init__(self):\n",
    "        # load images and store them\n",
    "        self.yellow_on = open(\"images/yellow_on.png\", \"rb\").read()\n",
    "        self.yellow_off = open(\"images/yellow_off.png\", \"rb\").read()\n",
    "\n",
    "        # display the user interface\n",
    "        # a button\n",
    "        self.button_switch = widgets.Button(description=\"Send 'switch'\")\n",
    "        self.button_switch.on_click(self.on_button_switch)\n",
    "        # another button\n",
    "        self.button_terminate = widgets.Button(description=\"Stop the Driver\")\n",
    "        self.button_terminate.on_click(self.on_button_terminate)\n",
    "        # an image of a yellow light\n",
    "        self.yellow = widgets.Image(\n",
    "            value=self.yellow_off, format='png', width=50, height=50)\n",
    "        # display everything\n",
    "        display(self.yellow, self.button_switch, self.button_terminate)\n",
    "\n",
    "    # called by our transition to turn the light on\n",
    "    def turn_yellow_on(self):\n",
    "        # switch on the yellow light\n",
    "        self.yellow.set_trait(name='value', value=self.yellow_on)\n",
    "\n",
    "    # called by our transition to turn the light on\n",
    "    def turn_yellow_off(self):\n",
    "        # switch off the yellow light\n",
    "        self.yellow.set_trait(name='value', value=self.yellow_off)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We declare the state machine using three transitions. As you can see, the effects on the transitions can refer to several methods, separated with a `;`.\n",
    "\n",
    "Run the cell below. You should see a blinking light. It stops when you click on the `Stop the Driver` button. To restart it, just run the cell again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "signal = SignalLight()\n",
    "\n",
    "t0 = {'source': 'initial',\n",
    "      'effect': 'start_timer(\"t\", 1000)',\n",
    "      'target': 'off'}\n",
    "t1 = {'trigger': 't',\n",
    "      'source': 'off',\n",
    "      'target': 'on',\n",
    "      'effect': 'turn_yellow_on; start_timer(\"t\", 1000)'}\n",
    "t2 = {'trigger': 't',\n",
    "      'source': 'on',\n",
    "      'target': 'off',\n",
    "      'effect': 'turn_yellow_off; start_timer(\"t\", 1000)'}\n",
    "\n",
    "machine = Machine(name='signal', transitions=[t0, t1, t2], obj=signal)\n",
    "signal.stm = machine\n",
    "\n",
    "driver = Driver()\n",
    "driver.add_machine(machine)\n",
    "driver.start()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sending Messages\n",
    "\n",
    "So far, the state machines were controlled by timers. We can also trigger the state machine by messages. The messages can come from different sources — hardware, software interrrupts, incoming communication packages, or, as here, clicks on a user interfaces.\n",
    "\n",
    "The button `Send Message switch` was not yet used in the example. Have a look again at the SignalLight class. When this button is pressed, a message `switch` is sent to the state machine. (Actually, its driver.) We can use this message to trigger the transition, so that we can control the signal light manually. (That doesn't make a lot of sense, but makes a simple example...)\n",
    "\n",
    "Execute the cell below. Nothing should happen, until you press the button `Send 'switch'`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "signal_2 = SignalLight()\n",
    "\n",
    "t0 = {'source': 'initial',\n",
    "      'target': 'off'}\n",
    "t1 = {'trigger':'switch',\n",
    "      'source':'off',\n",
    "      'target':'on',\n",
    "      'effect':'turn_yellow_on'}\n",
    "t2 = {'trigger':'switch', \n",
    "      'source':'on', \n",
    "      'target':'off', \n",
    "      'effect':'turn_yellow_off'}\n",
    "\n",
    "machine_2 = Machine(name='signal_2', transitions=[t0, t1, t2], obj=signal_2)\n",
    "signal_2.stm = machine_2\n",
    "\n",
    "driver_2 = Driver()\n",
    "driver_2.add_machine(machine_2)\n",
    "driver_2.start()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you press the `Stop the Driver` button, the driver will stop and your signals will not be forwarded to the state machine anymore. Restart the cell to start over again."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Repetition\n",
    "\n",
    "So what happend just now? \n",
    "\n",
    "* We declared a simple user interface.\n",
    "* The state machine can directly manipulate elements of this user interface, here by switching a lamp on and off, which basically means to change an image.\n",
    "* If we want to control the state machine from the user interface, we do this by sending a message from the user interface to the driver of the state machine, which then forwards it to the machine.\n",
    "* This message then triggers a transition.\n",
    "\n",
    "And we did that.... for WHAT????\n",
    "\n",
    "You will wonder why that is a good idea. After all, it may seem a bit complicated?\n",
    "\n",
    "Of course, in this very simple example, it may seem more complicated than you feel it should be. But this is because we make a minimal example so that the new lines of code are more obvious.\n",
    "\n",
    "By declaring these messages, we have decoupled the threads in the system. The user interface has its own thread, otherwise you could not scroll and use buttons while your program is busy. To synchronize the user interface with other processes, like the controller of our blinking light, we use messages. The benefit with these messages is that they don't block the caller, as a function would do. The caller just sends the message and continues, without being blocked. This \"untangles\" our concurrency problem, and we can solve it explicitly with states and transitions in the state machine. Here, we are much more flexible, which pays off once we have something slighlty more complex than the signal light.\n",
    "\n",
    "Remember:\n",
    "\n",
    "![](images/tweet.png)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}