Initial Commit

MrYsLab · Aug 10, 2023 · a5d9aea · a5d9aea
1 parent 14f4abf
commit a5d9aea
Show file tree

Hide file tree

Showing 78 changed files with 1,614 additions and 54 deletions.
diff --git a/docs/about.md b/docs/about.md
@@ -0,0 +1,21 @@
+# REPORTING ISSUES
+
+If you wish to report an issue with this library, please use
+[this link](https://github.com/MrYsLab/telemetrix-uno-r4/issues).
+
+For any of the servers, please use
+[this link](https://github.com/MrYsLab/Telemetrix4UnoR4/issuess).
+
+When filing an issue, please provide:
+
+1. Any console output.
+2. A description of the issue.
+3. Sample code demonstrating the problem.
+
+For bugs, comments, or questions, please use the links above.
+<br>
+<br>
+
+
+
+Copyright (C) 2023 Alan Yorinks. All Rights Reserved.
diff --git a/docs/about_the_apis.md b/docs/about_the_apis.md
@@ -0,0 +1,29 @@
+## Setting Pin Modes
+
+Pin modes must be set before interacting with a pin. All the methods listed
+below have a consistent API across all API classes.
+
+### Input Pin Modes
+
+#### Requiring A Callback To Be Specified
+* set_pin_mode_analog_input
+* set_pin_mode_dht
+* set_pin_mode_digital_input
+* set_pin_mode_digital_input_pullup
+* set_pin_mode_sonar
+
+#### Callback Specified In Read Commands
+* set_pin_mode_i2c
+* set_pin_mode_spi
+
+### Output Pin Modes
+* set_pin_mode_analog_output
+* set_pin_mode_digital_output
+* set_pin_mode_servo
+
+
+
+<br>
+<br>
+
+Copyright (C) 2023 Alan Yorinks. All Rights Reserved.
diff --git a/docs/app_creation.md b/docs/app_creation.md
@@ -0,0 +1,24 @@
+## A Word About The Application Templates
+
+The following section contains a set of application templates for each of the four 
+servers.
+The templates are based on the included examples.
+
+* [r4_minima_examples - asyncio](https://github.com/MrYsLab/telemetrix-uno-r4/tree/master/telemetrix_uno_r4/r4_minima_examples/asyncio)
+* [r4_minima_examples - threaded](https://github.com/MrYsLab/telemetrix-uno-r4/tree/master/telemetrix_uno_r4/r4_minima_examples/threaded)
+* [r4_wifi_examples_asyncio - BLE](https://github.com/MrYsLab/telemetrix-uno-r4/tree/master/telemetrix_uno_r4/r4_wifi_examples/asyncio/BLE)
+* [r4_wifi_examples_asyncio - WIFI](https://github.com/MrYsLab/telemetrix-uno-r4/tree/master/telemetrix_uno_r4/r4_wifi_examples/asyncio/WIFI)
+* [r4_wifi_examples_asyncio - usbSerial](https://github.com/MrYsLab/telemetrix-uno-r4/tree/master/telemetrix_uno_r4/r4_wifi_examples/asyncio/usbSerial)
+* [r4_wifi_examples_threaded - WIFI](https://github.com/MrYsLab/telemetrix-uno-r4/tree/master/telemetrix_uno_r4/r4_wifi_examples/threaded/WIFI)
+* [r4_wifi_examples_threaded - usbSerial](https://github.com/MrYsLab/telemetrix-uno-r4/tree/master/telemetrix_uno_r4/r4_wifi_examples/threaded/usbSerial)
+
+
+As you will see, your application needs to import the correct API 
+and instantiate the API class. 
+You then use the API method calls in writing your application.
+
+
+<br>
+<br>
+
+Copyright (C) 2023 Alan Yorinks. All Rights Reserved.
diff --git a/docs/arduino_ide.md b/docs/arduino_ide.md
@@ -0,0 +1,18 @@
+##  Download And Install The Arduino IDE
+
+Arduino IDE version 2.1.X is used to upload a server to the Minima or WIFI. It is also 
+used to modify server source code when configuration is necessary.
+
+To install a copy of the IDE, go to the [Arduino Software Download page](https://www.arduino.cc/en/software), and 
+select the version for your 
+operating system. Follow the installation instructions.
+
+![](images/arduino_ide_download.png)
+
+## A Note For Linux Users
+You may need to add your login to the dialout group to upload to the Arduino.
+
+To do so, follow [these instructions](https://support.arduino.cc/hc/en-us/articles/360016495679-Fix-port-access-on-Linux).
+
+<BR>
+Copyright (C) 2023 Alan Yorinks. All Rights Reserved.
diff --git a/docs/callbacks.md b/docs/callbacks.md
@@ -0,0 +1,94 @@
+## Registering A Callback
+
+A callback function must be registered when you set a pin to an input mode.
+
+The code below illustrates a typical callback function. 
+
+```angular2html
+def the_callback(data):
+    """
+    A callback function to report data changes.
+    This will print the pin number, its reported value and
+    the date and time when the change occurred
+
+    :param data: [pin mode, pin, current reported value, pin_mode, timestamp]
+    """
+    date = time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(data[CB_TIME]))
+    print(f'Report Type: {data[CB_PIN_MODE]} Pin: {data[CB_PIN]} '
+          f'Value: {data[CB_VALUE]} Time Stamp: {date}')
+```
+
+And here, the callback is registered when the set_pin_mode is called:
+
+```
+board.set_pin_mode_digital_input_pullup(12, the_callback)
+```
+
+If you forget to register a callback, 
+a RunTime exception will be thrown.
+
+```angular2html
+Traceback (most recent call last):
+  File "/home/afy/PycharmProjects/telemetrix-rpi-pico-w/ play/no_callback_registered.py", line 5, in <module>
+    board.set_pin_mode_digital_input(5)
+  File "/home/afy/PycharmProjects/telemetrix-rpi-pico-w/telemetrix_rpi_pico_w/telemetrix_rpi_pico_w.py", line 752, in set_pin_mode_digital_input
+    raise RuntimeError('A callback must be specified')
+RuntimeError: A callback must be specified
+```
+
+## Callback Function Parameter
+
+A callback function or method must accept a single parameter. The client 
+automatically fills in this parameter as a list 
+when receiving an input data change notification.  
+For "the_callback" above, this parameter is named data.
+
+The list contents vary from input pin type to input pin type and 
+are described in detail for each _set_pin_mode_XXX_ method in the
+[API documentation.](https://htmlpreview.github.io/?https://github.com/MrYsLab/telemetrix-rpi-pico/blob/master/html/telemetrix_rpi_pico/index.html) 
+The first element in the list identifies the pin type, and the last element
+is a timestamp of the data change occurrence. Other elements identify the GPIO pin, 
+the current data value, and additional relevant information.
+
+For example, the list may contain
+
+```angular2html
+[DIGITAL_REPORT, pin_number, pin_value, raw_time_stamp]
+
+DIGITAL_REPORT = 2
+```
+
+_**NOTE:**_
+
+**Telemetrix does not support polling or direct read methods for 
+inputs. Instead, the pin's associated callback is called as soon 
+as a data change is detected, allowing immediate response to data 
+changes and, generally, a more straightforward application design.
+**
+
+
+
+## Pin Types
+
+|                  **Pin Mode**                   |  **Pin Mode Value**  |
+|:-----------------------------------------------:|:--------------------:|
+|  Digital Input (including pullup and pulldown)  |          2           |
+|               Analog Input (ADC)                |          3           |
+|                       I2C                       |          10          |
+|                 SONAR Distance                  |          11          |
+|                       DHT                       |          12          |
+
+
+## Converting The Raw Timestamp
+
+To convert the raw timestamp field to a human-readable time, use **time.localtime()**.
+
+```angular2html
+date = time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(data[CB_TIME]))
+```
+
+
+<br>
+<br>
+
+Copyright (C) 2023 Alan Yorinks. All Rights Reserved.
diff --git a/docs/examples.md b/docs/examples.md
@@ -0,0 +1,36 @@
+Once the client and server software have been installed, 
+it would be an excellent time to try the examples.
+
+Examples are provided for all four of the servers.
+
+## Example Naming Conventions
+
+The naming convention used for the examples prefixes each example with three letters.
+The first letter is for the board type:
+
+* m = Minima
+* w = Wifi
+
+The second letter is for the transport type:
+
+* b = BLE
+* s = serial
+* w = WIFI
+
+The third is for the concurrency type:
+
+* a = asyncio
+* t = threaded
+
+## Links To The Examples
+
+* [r4_minima_examples - asyncio](https://github.com/MrYsLab/telemetrix-uno-r4/tree/master/telemetrix_uno_r4/r4_minima_examples/asyncio)
+* [r4_minima_examples - threaded](https://github.com/MrYsLab/telemetrix-uno-r4/tree/master/telemetrix_uno_r4/r4_minima_examples/threaded)
+* [r4_wifi_examples_asyncio - BLE](https://github.com/MrYsLab/telemetrix-uno-r4/tree/master/telemetrix_uno_r4/r4_wifi_examples/asyncio/BLE)
+* [r4_wifi_examples_asyncio - WIFI](https://github.com/MrYsLab/telemetrix-uno-r4/tree/master/telemetrix_uno_r4/r4_wifi_examples/asyncio/WIFI)
+* [r4_wifi_examples_asyncio - usbSerial](https://github.com/MrYsLab/telemetrix-uno-r4/tree/master/telemetrix_uno_r4/r4_wifi_examples/asyncio/usbSerial)
+* [r4_wifi_examples_threaded - WIFI](https://github.com/MrYsLab/telemetrix-uno-r4/tree/master/telemetrix_uno_r4/r4_wifi_examples/threaded/WIFI)
+* [r4_wifi_examples_threaded - usbSerial](https://github.com/MrYsLab/telemetrix-uno-r4/tree/master/telemetrix_uno_r4/r4_wifi_examples/threaded/usbSerial)
+
+<BR>
+Copyright (C) 2023 Alan Yorinks. All Rights Reserved.
diff --git a/docs/images/add_zip3.png b/docs/images/add_zip3.png
diff --git a/docs/images/arduino_ide_download.png b/docs/images/arduino_ide_download.png
diff --git a/docs/images/arduino_lib_install.png b/docs/images/arduino_lib_install.png
diff --git a/docs/images/ble_ino.png b/docs/images/ble_ino.png
diff --git a/docs/images/board_select_1.png b/docs/images/board_select_1.png
diff --git a/docs/images/board_select_2.png b/docs/images/board_select_2.png
diff --git a/docs/images/board_select_3.png b/docs/images/board_select_3.png
diff --git a/docs/images/board_select_4.png b/docs/images/board_select_4.png
diff --git a/docs/images/config_ble_server.png b/docs/images/config_ble_server.png
diff --git a/docs/images/config_serial_server.png b/docs/images/config_serial_server.png
diff --git a/docs/images/config_wifi_server.png b/docs/images/config_wifi_server.png
diff --git a/docs/images/delay.png b/docs/images/delay.png
diff --git a/docs/images/downloads.png b/docs/images/downloads.png
diff --git a/docs/images/example_1.png b/docs/images/example_1.png
diff --git a/docs/images/example_2.png b/docs/images/example_2.png
diff --git a/docs/images/example_3.png b/docs/images/example_3.png
diff --git a/docs/images/example_4.png b/docs/images/example_4.png
diff --git a/docs/images/example_5.png b/docs/images/example_5.png
diff --git a/docs/images/examples.png b/docs/images/examples.png
diff --git a/docs/images/get_examples.png b/docs/images/get_examples.png
diff --git a/docs/images/ide1.png b/docs/images/ide1.png
diff --git a/docs/images/install_t4a.png b/docs/images/install_t4a.png
diff --git a/docs/images/ip_address.png b/docs/images/ip_address.png
diff --git a/docs/images/library_manager_1.png b/docs/images/library_manager_1.png
diff --git a/docs/images/library_manager_2.png b/docs/images/library_manager_2.png
diff --git a/docs/images/library_manager_3.png b/docs/images/library_manager_3.png
diff --git a/docs/images/manage_libraries.png b/docs/images/manage_libraries.png
diff --git a/docs/images/no_port.png b/docs/images/no_port.png
diff --git a/docs/images/pinout.png b/docs/images/pinout.png
diff --git a/docs/images/router.png b/docs/images/router.png
diff --git a/docs/images/select_board_1.png b/docs/images/select_board_1.png
diff --git a/docs/images/select_server.png b/docs/images/select_server.png
diff --git a/docs/images/serial_ip.png b/docs/images/serial_ip.png
diff --git a/docs/images/serial_monitor.png b/docs/images/serial_monitor.png
diff --git a/docs/images/telemetrix4UnoR4.png b/docs/images/telemetrix4UnoR4.png
diff --git a/docs/images/telemetrix4arduino2.png b/docs/images/telemetrix4arduino2.png
diff --git a/docs/images/telemetrixunor4_2.png b/docs/images/telemetrixunor4_2.png
diff --git a/docs/images/tmx.png b/docs/images/tmx.png
diff --git a/docs/images/tmx10.png b/docs/images/tmx10.png
diff --git a/docs/images/tmx2.png b/docs/images/tmx2.png
diff --git a/docs/images/tmx3.png b/docs/images/tmx3.png
diff --git a/docs/images/tmx4.png b/docs/images/tmx4.png
diff --git a/docs/images/tmx5.png b/docs/images/tmx5.png
diff --git a/docs/images/tmx6.png b/docs/images/tmx6.png
diff --git a/docs/images/tmx7.png b/docs/images/tmx7.png
diff --git a/docs/images/tmx8.png b/docs/images/tmx8.png
diff --git a/docs/images/usb_ino.png b/docs/images/usb_ino.png
diff --git a/docs/images/warning.png b/docs/images/warning.png
diff --git a/docs/images/warning2.png b/docs/images/warning2.png
diff --git a/docs/images/wifi_ino.png b/docs/images/wifi_ino.png