TroubleShooting_FAQ.ipynb

{
  "nbformat": 4,
  "nbformat_minor": 0,
  "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.5"
    },
    "colab": {
      "provenance": [],
      "toc_visible": true,
      "include_colab_link": true
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "view-in-github",
        "colab_type": "text"
      },
      "source": [
        "<a href=\"https://colab.research.google.com/github/paulodowd/EMATM0054_53/blob/main/TroubleShooting_FAQ.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Amzupj4hKsWV"
      },
      "source": [
        "\n",
        "# FAQ / Trouble Shooting\n",
        "\n",
        "This labsheet covers the following topics:\n",
        "- No Serial Port / Cannot Upload.\n",
        "- I can't upload my code on Ubuntu (linux)\n",
        "- Unexpected results for float calculations\n",
        "- My if() statement isn't working.\n",
        "- Slower / Faster / Strange code with Serial.print().\n",
        "- Switch Case warning.\n",
        "\n",
        "\n",
        "You may also wish to look at the Check Point labsheets (0, 1, 2) for more general advice."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "kBvS_e6BKsWW"
      },
      "source": [
        "<br><br><br><br>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "vsVG6oJKKsWW"
      },
      "source": [
        "\n",
        "## No Serial Port / Cannot Upload:\n",
        "\n",
        "\n",
        "The 3Pi+ can sometimes lose its ability to connect to your computer.  Follow these steps to fix it.  On rare occasions, this problem can keep re-occuring, but this method can be repeated quickly and easily.\n",
        "\n",
        "\n",
        "### Step1\n",
        "- Open the Arduino IDE\n",
        "- Open the Blink Example\n",
        "    - Go to File -> Examples -> Basics -> Blink\n",
        "- Check that the board type `Arduino Leonardo` is selected\n",
        "    - Go to Tools -> Board -> Select `Arduino Leonardo` from the list.\n",
        "\n",
        "\n",
        "### Step 2\n",
        "- Enable `Show verbose output during: upload`\n",
        "    - Go to File -> Preferences\n",
        "    - Check the `upload` tick box, **so that it is ticked**.\n",
        "    \n",
        "<p align=\"center\">\n",
        "<img src=\"https://github.com/paulodowd/EMATM0054_53/blob/main/Images/verbose_upload.png?raw=true\">\n",
        "</p>\n",
        "\n",
        "### Step 3\n",
        "\n",
        "\n",
        "- Plug in your 3Pi+ to your computer via the USB cable.\n",
        "- Your computer might say \"device not recognised\", don't let this trouble you.\n",
        "- Go to Tools -> Port and make a note of which ports are available.  You may have many or none.\n",
        "\n",
        "### Step 4\n",
        "\n",
        "- Press the reset button twice - **quickly**\n",
        "    - The reset button is on the right of the robot, labelled \"Reset\" in white text.\n",
        "    - When you do this correctly, **you should see the built in LED fading**, as shown in the animated image below.\n",
        "    - Note that, the LED should slowly **fade** in and out, not blink on and off.\n",
        "    \n",
        "<p align=\"center\">\n",
        "<img src=\"https://github.com/paulodowd/EMATM0054_53/blob/main/Images/3Pi_ForcedUpload.gif?raw=true\" >\n",
        "</p>\n",
        "\n",
        "### Step 5\n",
        "\n",
        "- **Whilst the LED is fading**\n",
        "    - Go to Tools -> Port and select the newest Port which has shown up.\n",
        "    - If there isn't a new port, select the one with the highest value (e.g., COM10)\n",
        "    - Wait for the Fading LED to go out.  \n",
        "    - If you check Tools -> Port again, this new port may have gone.  This is OK.\n",
        "    \n",
        "### Step 6\n",
        "\n",
        "- Click the upload icon to upload the Blink code to your 3Pi+.\n",
        "- Wait for the code to compile. Wait until the Arduino IDE is searching for the port to connect to.  You will see something like the the white text appearing in the image below.\n",
        "- **When you see the Arduino IDE searching for a port, press the reset button twice (quickly) again to get the fading LED**.\n",
        "<p align=\"center\">\n",
        "<img src=\"https://github.com/paulodowd/EMATM0054_53/blob/main/Images/searching_for_port.png?raw=true\">\n",
        "</p>\n",
        "\n",
        "### Step 7\n",
        "\n",
        "Wait, and you should see text like the below image confirming the correct upload.  If not, try the process again.  Sometimes it can go wrong if you don't successsfully double-press the reset button quickly enough.  If, after a few attempts, you cannot get this to work, contact one of the teaching staff for the unit.\n",
        "<p align=\"center\">\n",
        "<img src=\"https://github.com/paulodowd/EMATM0054_53/blob/main/Images/success.png?raw=true\">\n",
        "</p>\n",
        "\n",
        "### Step 8\n",
        "\n",
        "You may wish to share this technique with your peers if they need help."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "EohWsRDyKsWX"
      },
      "source": [
        "<br><br><br><br>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "hEqJkwSoKsWX"
      },
      "source": [
        "## I can't upload my code on Ubuntu (linux)\n",
        "\n",
        "\n",
        "### Disabling ModemManager in Linux\n",
        "If you are using Linux and have trouble following the instructions above, your issue might be caused by a program called ModemManager. This program automatically connects to serial ports and sends modem commands to them, interfering with other software using those ports. You can run ps ax | grep -i Modem to see if ModemManager is running. On Ubuntu, the command to permanently disable ModemManager is:\n",
        "\n",
        "`sudo systemctl disable ModemManager`\n",
        "\n",
        "You should also check that you have access rights to the Serial port as it appears on your system."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "2F0vOVnvKsWX"
      },
      "source": [
        "<br><br><br><br>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "MJSnYM-FKsWX"
      },
      "source": [
        "## Unexpected results for float calculations\n",
        "\n",
        "\n",
        "\n",
        "If you are performing a calculation and your result is always 0 or `NaN`, it is highly likely that you have an issue with the **type** of your variable.  Remember that an `integer`, `long`, `char`, `byte` (etc) can only represent a whole number, whilst a `float` or a `double` can store fractional parts. Therefore, dividing two integers (or other similar type) will often result in a rounding error.   \n",
        "\n",
        "When we are writing calculations for the Arduino it is important to understand a general rule:\n",
        "- **read the operation from right-to-left**, excepting the normal mathematical rules.\n",
        "\n",
        "It is good practice to assume the compiler (or Arduino) is very stupid, and will make the worst choice for you.  Therefore, you should try to make sure you are always using the appropriate variable type.  If you have a good (smart) compiler which handles types well, lucky you!  But why take that risk?\n",
        "\n",
        "The following example within Arduino 1.8.13 will always report a result of 0, when (if done properly) it should report 0.5:\n",
        "```c\n",
        "  float result;\n",
        "  int a;\n",
        "  int b;\n",
        "\n",
        "  a = 1;\n",
        "  b = 2;\n",
        "\n",
        "  result = a / b;\n",
        "  \n",
        "  Serial.println( result );\n",
        "```\n",
        "In the above, if we read left-to-right, it appears as if the following line is going to operate as a float:\n",
        "```c\n",
        "  result = a / b;\n",
        "```\n",
        "...because we declared `result` as a `float`.  However, if we annotate our types and re-read the line from right-to-left:\n",
        "\n",
        "```c\n",
        "  [float]result = [int]a / [int]b;\n",
        "```\n",
        "...we can see that `a/b` takes place as integers.  In this case, the compiler assumes the type on the right-hand side is (`int`), and executes the operation as `int` in working memory, and only afterwards stores the result into a `float`.  So your `result` will always store a 0 (rounding error).\n",
        "\n",
        "To perform the above calculation a safer manner, the calculation can be broken into explicit steps, making use of <a href=\"https://www.arduino.cc/en/Reference/Cast\">typecasting</a>, which also helps with the readability of your code:\n",
        "```c\n",
        "  float result;\n",
        "  int a;\n",
        "  int b;\n",
        "\n",
        "  a = 1;\n",
        "  b = 2;\n",
        "\n",
        "  result = (float)a;\n",
        "  result = result / (float)b;\n",
        "  \n",
        "  Serial.println( result );\n",
        "```\n",
        "\n",
        "\n",
        "You will also see this phenomenon when working with hard-coded constants (\"magic numbers\").  The following code example will also produce a result of 0 on Arduino 1.8.13:\n",
        "\n",
        "\n",
        "```c\n",
        "  float result;\n",
        "  \n",
        "  result = 1 / 2;\n",
        "  \n",
        "  Serial.println( result );\n",
        "```\n",
        "\n",
        "In the above, \"1\" and \"2\" have not been declared as variables, and therefore the compiler has to make a decision for you about what type they are.  Because they are written as whole numbers, the compiler decides they are `integers`, causing the same error as above.  \n",
        "\n",
        "You can work successfully with declared constants with the following minor adjustment, which prompts the compiler to treat the numbers as type `float`:\n",
        "\n",
        "```c\n",
        "  float result;\n",
        "  \n",
        "  result = 1.0 / 2.0;\n",
        "  \n",
        "  Serial.println( result );\n",
        "```"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "XtJzsZkqKsWY"
      },
      "source": [
        "<pre>\n",
        "<br><br><br>\n",
        "</pre>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Nl-Lvv9JKsWY"
      },
      "source": [
        "## My if() statement isn't working\n",
        "\n",
        "The following compiles without any errors or warnings, but should be considered **incorrect**:\n",
        "\n",
        "```c\n",
        "if( 1 < x < 10 ) {\n",
        "    \n",
        "}\n",
        "```\n",
        "\n",
        "The behaviour of the above is unknown.  A safer, better determined syntax is available.  In C and Arduino, the condition of an if() statement is evaluated to be either true or false as a single entity.  **The above would be better written as**:\n",
        "\n",
        "```c\n",
        "if( ( 1 < x ) && ( x < 10 ) ) {\n",
        "    \n",
        "}\n",
        "```\n",
        "\n",
        "In the above:\n",
        "- the right-hand condition is evaluated, `1 < x` (true or false)\n",
        "- the left-hand condition is evaluated, `x < 10` (true or false)\n",
        "- both results are then evaluated together against `&&` (true of false)\n",
        "- which results in a single conditional evaluation to pass or fail as true or false.\n",
        "\n",
        "If we return to the first example, we can imagine `x` has a value of 1:\n",
        "\n",
        "```c\n",
        "if( 1 < 1 < 10 ) {\n",
        "    \n",
        "}\n",
        "```\n",
        "\n",
        "When we attempt to resolve this statement, we can consider that:\n",
        "- `( 1 < 1 )` is false.\n",
        "- `( 1 < 10 )` is true.\n",
        "\n",
        "We don't know whether the machine code will resolve to fail the left-side, or pass the right-side.  So if you wish to make more than one conditional evaluation:\n",
        "- you should use the `&&` and `||` operators\n",
        "- or use multiple nested if() statements.\n",
        "\n",
        "### Another common problem with if() statements:\n",
        "\n",
        "Another common problem with if() statements is to use the single equals sign `=` which acts as an assignment of value (stores a value), rather than the double equals sign which acts as as evaluation.  Again, unfortunately, the compiler will not prompt you with a warning or error:\n",
        "\n",
        "```c\n",
        "int a = 1;\n",
        "int b = 2;\n",
        "\n",
        "// This is incorrect.\n",
        "// a will be assigned b's value.\n",
        "if( a = b ) {\n",
        "    // This will run if 'a' receives a positive, non-zero value.\n",
        "}\n",
        "\n",
        "// This is correct.\n",
        "// a will be evaluated against b.\n",
        "if( a == b ) {\n",
        "    \n",
        "}\n",
        "\n",
        "```\n",
        "\n",
        "### Yet another common problem with if() statements\n",
        "\n",
        "It is valid syntax to use an if() statement without curly-braces `{}`.  This can be useful if you have only one line of code to operate.  However, it is advised you always use curly-braces to avoid any potential confusion.  Consider the following example:\n",
        "\n",
        "```c\n",
        "if( a == b )\n",
        "    processA();\n",
        "    discardB();\n",
        "```\n",
        "\n",
        "In the above function, it looks like `processA()` and `processB()` will run as a result of the if() statement.  In fact, the way the above will resolve is as following:\n",
        "\n",
        "```c\n",
        "if( a == b ) {\n",
        "    processA();\n",
        "}\n",
        "discardB();   //this will always happen, regardless of the if()\n",
        "```\n",
        "\n",
        "This can also be confusing if else statements are used, for the same reason:\n",
        "\n",
        "\n",
        "```c\n",
        "if( a == b )\n",
        "    processA();\n",
        "else\n",
        "    processB();\n",
        "    discardA();\n",
        "```\n",
        "\n",
        "Again, the above will actually resolve to behave as the following:\n",
        "\n",
        "```c\n",
        "if( a == b ) {\n",
        "    processA();\n",
        "} else {\n",
        "    processB();\n",
        "}\n",
        "discardA();\n",
        "```\n",
        "\n",
        "To save yourself time debugging, make a habit of always using curly-braces - that way the intention of your code is always clear.\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "tcOJFqoKKsWZ"
      },
      "source": [
        "<br><br><br><br>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "eu6GMt6nKsWZ"
      },
      "source": [
        "\n",
        "# Slower / Faster / Strange code with Serial.print()\n",
        "\n",
        "There is a known issue with `Serial.print` and `Serial.println` on the 3Pi+.  You may find that your  3Pi+ becomes irratic or the timing of its behaviour changes when you unplug the USB cable.  Sometimes, you may unplug your  3Pi+ and it works fine for 2 minutes, and then goes crazy. This appears to be an error with Serial Print.\n",
        "\n",
        "There are two steps required to fix this problem.  \n",
        "\n",
        "## Step 1:\n",
        "\n",
        "Include the following code at the top of your main program (the first tab in the Arduino IDE):\n",
        "\n",
        "```c\n",
        "#include <USBCore.h>    // To fix serial print behaviour bug.\n",
        "u8 USB_SendSpace(u8 ep);\n",
        "#define SERIAL_ACTIVE (USB_SendSpace(CDC_TX) >= 50)\n",
        "```\n",
        "\n",
        "Note that, if you use `Serial.print` or `Serial.println` within other source files, you may need to include this at the top of those files too.  Try to compile your code without it, and see if there are useful errors.  \n",
        "\n",
        "## Step 2:\n",
        "\n",
        "At every location you use `Serial.print` or `Serial.println`, you should wrap your code in the following way:\n",
        "\n",
        "```c\n",
        "if( SERIAL_ACTIVE ) {\n",
        "\n",
        "  Serial.print(\"An example\");\n",
        "  Serial.println(\" of fixing the serial bug\");\n",
        "}\n",
        "```\n",
        "\n",
        "This will allow you to plug in and remove the USB cable without effecting the performance of your Robot.  \n",
        "\n",
        "Note that, you can also use `if( SERIAL_ACTIVE ) { }` to create different behaviours depending on whether your robot is plugged into USB or not.\n",
        "\n",
        "\n",
        "\n",
        "        \n",
        "        \n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "99F_TEBrKsWZ"
      },
      "source": [
        "<br><br><br><br>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "oek9qCApKsWZ"
      },
      "source": [
        "# Switch Case Warning\n",
        "\n",
        "From previous experience on this unit, there is occasionally an issue where the standard `switch case` selection mechanism does not operate properly.  You may find that even though your conditional statement is valid, the `switch case` fails to enter the valid case and execute code.  It is not known why this happens - presumably there is a bug in the compiler.\n",
        "\n",
        "**It is strongly advised to avoid using a Switch Case statements.** Even though this bug is intermittent, it is best to not risk encountering the error.\n",
        "\n",
        "A switch case looks like:\n",
        "\n",
        "```c\n",
        "switch( my_variable_to_evaluate ) {\n",
        "        \n",
        "    case value_1: someCode1();\n",
        "        break;\n",
        "    case value_2: someCode2();\n",
        "        break;\n",
        "        // etc\n",
        "    default:\n",
        "        someCode3();\n",
        "}\n",
        "```\n",
        "\n",
        "The same functionality can be gained with `if()elseif` statments, such as:\n",
        "\n",
        "```c\n",
        "if( my_variable_to_evaluate == value_1 ) {\n",
        "    someCode1();\n",
        "} else if( my_variable_to_evaluate == value_2 ) {\n",
        "    someCode2();\n",
        "} else {  // behaves like default:\n",
        "    someCode3();\n",
        "}\n",
        "```"
      ]
    }
  ]
}