Revision 8:a9014ff96696, committed 2020-12-28

Comitter:

asreed

Date:

Mon Dec 28 17:25:30 2020 +0000

Parent:

7:40cc50a2fed1

Child:

9:695630f5ffd3

Commit message:

Added a few basic comments and updated the readme.md

Changed in this revision

--- a/README.md	Mon Dec 28 00:49:38 2020 +0000
+++ b/README.md	Mon Dec 28 17:25:30 2020 +0000
@@ -1,49 +1,42 @@
-![](./resources/official_armmbed_example_badge.png)
-# Blinky Mbed OS example
-
-The example project is part of the [Arm Mbed OS Official Examples](https://os.mbed.com/code/) and is the [getting started example for Mbed OS](https://os.mbed.com/docs/mbed-os/v5.14/quick-start/index.html). It contains an application that repeatedly blinks an LED on supported [Mbed boards](https://os.mbed.com/platforms/).
-
-You can build the project with all supported [Mbed OS build tools](https://os.mbed.com/docs/mbed-os/latest/tools/index.html). However, this example project specifically refers to the command-line interface tool [Arm Mbed CLI](https://github.com/ARMmbed/mbed-cli#installing-mbed-cli).
-(Note: To see a rendered example you can import into the Arm Online Compiler, please see our [import quick start](https://os.mbed.com/docs/mbed-os/latest/quick-start/online-with-the-online-compiler.html#importing-the-code).)
-
-1. [Install Mbed CLI](https://os.mbed.com/docs/mbed-os/latest/quick-start/offline-with-mbed-cli.html).
+![]()
+# Initially based on the Blinky Mbed OS example
 
-1. Clone this repository on your system, and change the current directory to where the project was cloned:
-
-    ```bash
-    $ git clone git@github.com:armmbed/mbed-os-example-blinky && cd mbed-os-example-blinky
-    ```
+This project is one example of the CITY1082 assignment one: Environmental Control System
 
-    Alternatively, you can download the example project with Arm Mbed CLI using the `import` subcommand:
-
-    ```bash
-    $ mbed import mbed-os-example-blinky && cd mbed-os-example-blinky
-    ```
-
+Tested with Mbed online compiler and mbed Studio untested with cli but should be fine.
 
 ## Application functionality
 
-The `main()` function is the single thread in the application. It toggles the state of a digital output connected to an LED on the board.
+The `main()` function is one of two threads in the application. 
+After reset and initialisation it toggles the state of a digital output connected 
+to an LED on the board periodically, reads the temperature and light level sensors,
+sets or activates any heating and lighting controls connected to the microcontroller,
+updates the display data using a vt100 terminal emulator console, then repeats the
+loop.
+A second thread `consoleThread()` accepts keyboard input from the terminal emulator
+and processes any characters received:
+  '<sp>'  Set max and minimum threshold values for heating temperature and
+          light levels.
+  '<tab>' Shift focus between thresholds to adjust them individually.
+  'MH'    Toggle Auto/Manual for heating
+      'H' when in manual mode toggle heating on or off
+  'ML'    Toggle Auto/Manual for lighting
+      'L' when in manual mode toggle lighting on or off
+  'T'     Set the current Time and Date (DD/MM/YYYY HH:MM:SS)
+ 
+  simple line editor to accept numeric values typed on keyboard (needs some 
+  error checking of input values to avoid mistypes causing mbed to crash).
+ 
 
 ## Building and running
 
 1. Connect a USB cable between the USB port on the board and the host computer.
-2. <a name="build_cmd"></a> Run the following command to build the example project and program the microcontroller flash memory:
-    ```bash
-    $ mbed compile -m <TARGET> -t <TOOLCHAIN> --flash
-    ```
-The binary is located at `./BUILD/<TARGET>/<TOOLCHAIN>/mbed-os-example-blinky.bin`.
-
-Alternatively, you can manually copy the binary to the board, which you mount on the host computer over USB.
-
-Depending on the target, you can build the example project with the `GCC_ARM`, `ARM` or `IAR` toolchain. After installing Arm Mbed CLI, run the command below to determine which toolchain supports your target:
-
-```bash
-$ mbed compile -S
-```
+2. Online compiler - click compile and save to board
+   mbed Studio - click build and run terminal emulator is built in (115200 baud).
 
 ## Expected output
-The LED on your target turns on and off every 500 milliseconds.
+The LED on your target turns on and off every 500 milliseconds. VT100 terminal
+emulator display shows current settings and readng from sensors.
 
 
 ## Troubleshooting

--- a/main.cpp	Mon Dec 28 00:49:38 2020 +0000
+++ b/main.cpp	Mon Dec 28 17:25:30 2020 +0000
@@ -12,8 +12,8 @@
 //#define POOR_MANS
 #define UTF8 // select vt100 line drawing set
 #include "VT100.h"
+
 // Page elements positions
-
 #define TLINE   4  // line where temperature values are displayed
 #define LLINE   6  //   "    "   light......          
 #define TLPOS   2  // Temperature  and light level displays start on this line
@@ -42,6 +42,24 @@
 #define PAGEWIDTH 70
 #define PAGELENGTH 19
 
+/*******************************************************************************
+ *
+ * page[][] 2d representation of the screen border display
+ *
+ * 
+ * j - Bottom right _|
+ * k - Top right corner
+ * l - top left corner
+ * m - Bottom left |_
+ * n - cross +
+ * q - horizontal bar
+ * t - left hand |-
+ * u - right hand -|
+ * v - Bottom with line up
+ * w - top with line down
+ * x - vertical bar |
+ *
+ ******************************************************************************/
 char page[PAGELENGTH][PAGEWIDTH] = {
     "lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqwqqqqqqqqqqqqqqqwqqqqqqqqqqqqqqqqk\r\n",
     "x                               x               x                x\r\n",
@@ -70,12 +88,9 @@
 char buffer[80];
 Thread thread;
 bool allowUpdate = true;
-char blockChar[4];
-int charLen;
 
 time_t currentTime;
 
-
 FileHandle *mbed::mbed_override_console(int fd)
 {
     return &serial_port;
@@ -113,8 +128,8 @@
 } myData;
 
 /* prototype of function */
-void posCursor(int x, int y);
-void displayAt( int x, int y, char *buffer );
+void posCursor(int col, int line);
+void displayAt( int col, int line, char *strBuffer );
 void initialise();
 void readSensors();
 void setActuators();
@@ -122,7 +137,26 @@
 void drawBorders();
 void updateRealTimeClock(char *timeBuffer);
 
-/* console thread */
+/*******************************************************************************
+ *
+ * console keyboard scanning thread 
+ *
+ * Started after reset 
+ *
+ * Checks for characters from the serial link, decodes the requested action:
+ *
+ * '<sp>'  Set max and minimum threshold values for heating temperature and
+ *         light levels.
+ * '<tab>' Select between individual thresholds to adjust.
+ * 'MH'    Toggle Auto/Manual for heating
+ *     'H' when in manual mode toggle heating on or off
+ * 'ML'    Toggle Auto/Manual for lighting
+ *     'L' when in manual mode toggle lighting on or off
+ * 'T'     Set the current Time and Date (DD/MM/YYYY HH:MM:SS)
+ *
+ * simple line editor to accept values typed on keyboard
+ *
+ */
 void consoleThread()
 {
     char inputStr[20];
@@ -354,11 +388,12 @@
 int main()
 {
     initialise(); // function to setup VT100 display
-    thread.start( consoleThread );
+    thread.start( consoleThread ); // Start the console keyboard input thread
     /****************************************************************************
      *
      * Main loop:-
      *
+     * 
      * flash status led
      * read sensors to get current environmental conditions
      * set actuators to turn on the appropriate heating/cooling and lighting
@@ -396,6 +431,16 @@
     if ((myData.lightingStatus == 0) && (myData.ambientLight < myData.lowLightThresh) && (myData.lightingMode == 0)) myData.lightingStatus = 1;  // turn on
     if ((myData.lightingStatus == 1) && (myData.ambientLight > myData.highLightThresh) && (myData.lightingMode == 0)) myData.lightingStatus = 0; // turn off
 }
+
+/*******************************************************************************
+ *
+ * displayData()
+ *
+ * Update all sensor and actuator mimic fields with current values
+ *
+ * LED simulation uses reverse video space in the colour of the text field
+ *
+ ******************************************************************************/
 void displayData()
 {
 //    int tCol, lCol;
@@ -410,19 +455,16 @@
 
     if (myData.ambientTemp > myData.highTempThresh) {
         RED_BOLD;
-//        REVERSE;
-        displayAt(TLLED, TLINE, buffer);
+        displayAt(TLLED, TLINE, buffer); // LED simulation reverse video space
         NORMAL;
         RED_BOLD;
     } else if (myData.ambientTemp < myData.lowTempThresh) {
         BLUE_BOLD;
-//        REVERSE;
         displayAt(TLLED, TLINE, buffer);
         NORMAL;
         BLUE_BOLD;
     } else {
         GREEN_BOLD;
-//        REVERSE;
         displayAt(TLLED, TLINE, buffer);
         NORMAL;
         GREEN_BOLD;
@@ -462,19 +504,16 @@
 
     if (myData.ambientLight > myData.highLightThresh) {
         RED_BOLD;
-//        REVERSE;
         displayAt(TLLED, LLINE, buffer);
         NORMAL;
         RED_BOLD;
     } else if (myData.ambientLight < myData.lowLightThresh) {
         BLUE_BOLD;
-//        REVERSE;
         displayAt(TLLED, LLINE, buffer);
         NORMAL;
         BLUE_BOLD;
     } else {
         GREEN_BOLD;
-//        REVERSE;
         displayAt(TLLED, LLINE, buffer);
         NORMAL;
         GREEN_BOLD;
@@ -512,30 +551,57 @@
     WHITE_BOLD;
     displayAt(RTCCOL, STATUS, timeBuffer);
 }
-
+/*******************************************************************************
+ *
+ * setActuators()
+ *
+ * Control switches/relays for hardware connected to the environmental control
+ * system
+ *
+ ******************************************************************************/
 void setActuators()
 {
     boilerLed = myData.heatingStatus;
     lightingLed = myData.lightingStatus;
 }
 
-void displayAt( int x, int y, char *buffer )
+/*******************************************************************************
+ *
+ * displayAt( column, line, string )
+ *
+ * Move the VT100 cursor to new coordinates on the display and print a string
+ * of characters.
+ *
+ ******************************************************************************/
+void displayAt( int col, int line, char *strBuffer )
 {
     {
-        printf( "\033[%d;%dH%s", y, x, buffer);
+        printf( "\033[%d;%dH%s", line, col, strBuffer);
         fflush(stdout);
     }
 }
-
-void posCursor(int x, int y)
+/*******************************************************************************
+ *
+ * posCursor( column, line )
+ *
+ * Move the VT100 cursor to precise coordinates on the display
+ *
+ ******************************************************************************/
+void posCursor(int col, int line)
 {
 
     {
-        printf( "\033[%d;%dH", y, x);
+        printf( "\033[%d;%dH", line, col);
         fflush(stdout);
     }
 }
-
+/*******************************************************************************
+ *
+ * initialise()
+ *
+ * Called once following reset to setup the vt100 screen console display
+ *
+ ******************************************************************************/
 
 void initialise()
 {
@@ -565,16 +631,27 @@
     displayAt(FCOL, USRHLP+3, (char *)"* Press \"M key\" to change auto/manual modes");
     displayAt(FCOL, USRHLP+4, (char *)"* Press \"T key\" to set the current time");
     fflush(stdout); // send the codes to the terminal
-    charLen = strlen(BLOCK);
-    strcpy(blockChar, BLOCK); // make a pointer to the rectangular block for LEDs
 }
 
+/*******************************************************************************
+ *
+ * drawBorders()
+ *
+ * Converts the grid of lines and corners defined in page[][] to a printable
+ * string of characters appropriate to the font of the terminal emulator.
+ * UTF8 character set is the most commonly used with vt100 on PUTTY or Teraterm.
+ * Each shape is defined by three bytes in UTF8.
+ * Other supported modes are POOR_MANS  +, -, | and VT100 one byte graphic 
+ * characters these are non-standard and not universally supported in all or
+ * even many fonts.
+ *
+ ******************************************************************************/
 void drawBorders()
 {
     char outStr[1040];
     char outChar[4];
     int where;
-//    int charLen;
+    int charLen;
 #ifdef GRAPHIC_SET
     printf("%c", GRAPHIC_SET);
 #endif
@@ -670,7 +747,18 @@
     printf("%c", TEXT_SET);
 #endif
 }
-// Update RTC
+/*******************************************************************************
+ *
+ * Update RTC function
+ *
+ * Take a string from the console thread when the user sets the time.
+ * Decodes the string and uses the data to set the time and date.
+ *
+ * TODO: needs some error checking as any errors in the input string causes 
+ *       mbed to crash.
+         Could use NTP to set time when wifi connectivity is added
+ *
+ ******************************************************************************/
 void updateRealTimeClock(char *timeBuffer)
 {
     char *tp;