Updates to the examples

- Minor updates to the examples.
- Additional example of using mDNS to browse for WiThrottle servers
- Additional example of using multiThrottle methods

README.md

@@ -12,7 +12,7 @@ First of all, this library implements the WiThrottle protocol in a non-blocking
 
 These patterns (Dependency Injection and Delegation) allow you to keep the different parts of your sketch from becoming too intertwined with each other.  Nothing in the code that manages the pushbuttons or speed knobs needs to have any detailed knowledge of the WiThrottle network protocol.
 
-## Differences from the original library
+## Differences in the lucadentella version from the original library by David Zuhn
 
 https://github.com/davidzuhn/WiThrottleProtocol
 
@@ -22,18 +22,20 @@ https://github.com/davidzuhn/WiThrottleProtocol
  - Added a setter method for delegate class: setDelegate()
  - Added the ability to parse roster messages and to receive the roster list via delegate class
 
- ## Differences from the lucadentella version of the library
+ ## Differences in this version from the lucadentella version of the library
 
  https://github.com/lucadentella/WiThrottle
 
  - Added the trademark changes from the original library
- - supports multi-throttle commands (max 6)  (Added in version 1.1.0)
+ - Support multi-throttle commands (max 6)  (Added in version 1.1.0)
  - Support added for on-the-fly consists
  - Support added for turnouts/points
  - Support added for routes
  - Heartbeat sends the device name, which forces the WiThrottle server to respond (used to confirm it is still connected)
  - minimum time separation/delay between commands sent (introduced in v1.1.7)
- - bug fixes
+ - Support for broadcast messages and alerts (introduced in v1.1.12)
+ - Added logging levels (introduced in v1.1.18/19)
+ - Lots of bug fixes
 
 ## Included examples
 
@@ -46,6 +48,7 @@ Change the WiFi settings and enter the IP address of the computer running JMRI (
 const char* ssid = "MySSID";
 const char* password =  "MyPWD";
 IPAddress serverAddress(192,168,1,1);
+int serverPort = 12090;
 ```
 Compile and run, you should see a new client connected in JMRI:
 
@@ -77,7 +80,25 @@ Compile and run, you should see in the Serial monitor the list of locomotives as
 
 ![](https://github.com/flash62au/WiThrottleProtocol/raw/master/images/roster-example.jpg)
 
-## Public Methods and atributes
+### WiThrottleProtocol_mDNS
+
+Example to show how to browse for WiThrottle mDNS servers.
+
+The example lists the discovered server in the serial monitor and connects to the first one found.
+
+Compile and run, you should see in Serial monitor the discovered WiThrottle servers.
+
+### WiThrottleProtocol_multiThrottle
+
+Example to show how to use the multiThrottle methods.
+
+This sketch connects to the first discovered server and acquires locos 10 and 11 in throttles 0 and 1.  It then reverses their direction every 5 seconds.
+
+Compile and run.  To best see this in action, use a controller app like Engine Driver (android) or WiThrottle (iOS) and acquire locos 10 and 11 in separate throttles.  You will see their direction change every 5 seconds.
+
+---
+
+## Public Methods and attributes
 
 see https://flash62au.github.io/WiThrottleProtocol/library.html
 
@@ -87,13 +108,22 @@ see https://flash62au.github.io/WiThrottleProtocol/library.html
  - Update the examples
  - Add multithrottle examples
  - Finish the in-code documentation 
- - Write Tests
  - Better Parser (Antlr?)
 
  ## Usage Notes
 
+ ### Multithrottle Support
+
  - When I added the multithrottle support I have done my best to maintain backwards compatibility.  As a result if you use the non-multithrottle versions of any of the methods, the *default* multithrottle is now defunct 'T' rather than the now standard '0'.<br/>That means that you ***cannot mix*** multithrottle and non-multithrottle versions of the methods in your code.
 
+ ### WiFi limitations
+
+ This is **not** a limitation of the library, but of the ESP32 architecture.
+
+ The ESP32 *cannot use the 5gHz* frequencies.  It is limited to the 2.4gHz  frequencies. 
+
+ It also seems to be *unable to use channels beyond 10* (and I have seen it struggle with channel 10 itself.)
+
 ----
 ----
 

examples/WiThrottleProtocol_Basic/WiThrottleProtocol_Basic.ino

@@ -4,12 +4,14 @@
 // and how to connect to a WiThrottle protocol server using static IP
 // Tested with ESP32-DEVKITC development board
 //
-// Luca Dentella, 2020
+// Luca Dentella, 2020; Peter Akers, 2025
 
 #include <WiFi.h>
 #include <WiThrottleProtocol.h>
 
 // WiFi and server configuration
+// Note: the ESP32 can only use the 2.4gHz frequences (not 5gHz) 
+// and only channels below 10
 const char* ssid = "MySSID";
 const char* password =  "MyPWD";
 IPAddress serverAddress(192,168,1,1);
@@ -21,18 +23,28 @@ WiThrottleProtocol wiThrottleProtocol;
 
 void setup() {
 
+  delay(5000); // this pause added only to help with debugging 
+               // to give youy a chnace to open the serila monitor.
+               // You would not normally have it.
+
   Serial.begin(115200);
-  Serial.println("WiThrottleProtocol Basic Demo");
+  Serial.println("WiThrottleProtocol Delegate Demo");
   Serial.println();
 
   // Connect to WiFi network
-  Serial.println("Connecting to WiFi.."); 
+  Serial.println("Connecting to WiFi..."); 
   WiFi.begin(ssid, password);
-  while(WiFi.status() != WL_CONNECTED) delay(1000);  
+
+  while(WiFi.status() != WL_CONNECTED) {
+    Serial.println("Trying to connect...");
+    delay(1000);  
+  }
+
   Serial.print("Connected with IP: "); Serial.println(WiFi.localIP());
 
   // Connect to the server
-  Serial.println("Connecting to the server...");
+  Serial.print("Connecting to the server: "); 
+  Serial.print(serverAddress); Serial.print(":"); Serial.println(serverPort);
   if (!client.connect(serverAddress, serverPort)) {
     Serial.println("connection failed");
     while(1) delay(1000);

examples/WiThrottleProtocol_Delegate/WiThrottleProtocol_Delegate.ino

@@ -3,7 +3,7 @@
 // Shows how to create a delegate class to handle callbacks
 // Tested with ESP32-DEVKITC development board
 //
-// Luca Dentella, 2020
+// Luca Dentella, 2020; Peter Akers, 2025
 
 #include <WiFi.h>
 #include <WiThrottleProtocol.h>
@@ -18,6 +18,8 @@ class MyDelegate : public WiThrottleProtocolDelegate {
 };
 
 // WiFi and server configuration
+// Note: the ESP32 can only use the 2.4gHz frequences (not 5gHz) 
+// and only channels below 10
 const char* ssid = "MySSID";
 const char* password =  "MyPWD";
 IPAddress serverAddress(192,168,1,1);
@@ -30,18 +32,28 @@ MyDelegate myDelegate;
 
 void setup() {
 
+  delay(5000); // this pause added only to help with debugging 
+               // to give youy a chnace to open the serila monitor.
+               // You would not normally have it.
+
   Serial.begin(115200);
   Serial.println("WiThrottleProtocol Delegate Demo");
   Serial.println();
 
   // Connect to WiFi network
-  Serial.println("Connecting to WiFi.."); 
+  Serial.println("Connecting to WiFi..."); 
   WiFi.begin(ssid, password);
-  while(WiFi.status() != WL_CONNECTED) delay(1000);  
+
+  while(WiFi.status() != WL_CONNECTED) {
+    Serial.println("Trying to connect...");
+    delay(1000);  
+  }
+
   Serial.print("Connected with IP: "); Serial.println(WiFi.localIP());
 
   // Connect to the server
-  Serial.println("Connecting to the server...");
+  Serial.print("Connecting to the server: "); 
+  Serial.print(serverAddress); Serial.print(":"); Serial.println(serverPort);
   if (!client.connect(serverAddress, serverPort)) {
     Serial.println("connection failed");
     while(1) delay(1000);

examples/WiThrottleProtocol_FastTime/WiThrottleProtocol_FastTime.ino

@@ -5,13 +5,15 @@
 // DO NOT use Serial Monitor but a "real" terminal (PuTTY, RealTerm) 
 // Tested with ESP32-DEVKITC development board
 //
-// Luca Dentella, 2020
+// Luca Dentella, 2020; Peter Akers, 2025
 
 #include <WiFi.h>
 #include <WiThrottleProtocol.h>
 #include <TimeLib.h>
 
 // WiFi and server configuration
+// Note: the ESP32 can only use the 2.4gHz frequences (not 5gHz) 
+// and only channels below 10
 const char* ssid = "MySSID";
 const char* password =  "MyPWD";
 IPAddress serverAddress(192,168,1,1);
@@ -24,18 +26,28 @@ unsigned long lastPrint = 0;
 
 void setup() {
 
+  delay(5000); // this pause added only to help with debugging 
+               // to give youy a chnace to open the serila monitor.
+               // You would not normally have it.
+
   Serial.begin(115200);
-  Serial.println("WiThrottleProtocol FastTime Demo");
+  Serial.println("WiThrottleProtocol Delegate Demo");
   Serial.println();
 
   // Connect to WiFi network
-  Serial.println("Connecting to WiFi.."); 
+  Serial.println("Connecting to WiFi..."); 
   WiFi.begin(ssid, password);
-  while(WiFi.status() != WL_CONNECTED) delay(1000);  
+
+  while(WiFi.status() != WL_CONNECTED) {
+    Serial.println("Trying to connect...");
+    delay(1000);  
+  }
+
   Serial.print("Connected with IP: "); Serial.println(WiFi.localIP());
 
   // Connect to the server
-  Serial.println("Connecting to the server...");
+  Serial.print("Connecting to the server: "); 
+  Serial.print(serverAddress); Serial.print(":"); Serial.println(serverPort);
   if (!client.connect(serverAddress, serverPort)) {
     Serial.println("connection failed");
     while(1) delay(1000);

examples/WiThrottleProtocol_Roster/WiThrottleProtocol_Roster.ino

@@ -3,7 +3,7 @@
 // Shows how to use a delegate class to receive the roster list
 // Tested with ESP32-DEVKITC development board
 //
-// Luca Dentella, 2020
+// Luca Dentella, 2020; Peter Akers, 2025
 
 #include <WiFi.h>
 #include <WiThrottleProtocol.h>
@@ -23,6 +23,8 @@ class MyDelegate : public WiThrottleProtocolDelegate {
 };
 
 // WiFi and server configuration
+// Note: the ESP32 can only use the 2.4gHz frequences (not 5gHz) 
+// and only channels below 10
 const char* ssid = "MySSID";
 const char* password =  "MyPWD";
 IPAddress serverAddress(192,168,1,1);
@@ -35,18 +37,28 @@ MyDelegate myDelegate;
 
 void setup() {
 
+  delay(5000); // this pause added only to help with debugging 
+               // to give youy a chnace to open the serila monitor.
+               // You would not normally have it.
+
   Serial.begin(115200);
-  Serial.println("WiThrottleProtocol Roster Demo");
+  Serial.println("WiThrottleProtocol Delegate Demo");
   Serial.println();
 
   // Connect to WiFi network
-  Serial.println("Connecting to WiFi.."); 
+  Serial.println("Connecting to WiFi..."); 
   WiFi.begin(ssid, password);
-  while(WiFi.status() != WL_CONNECTED) delay(1000);  
+
+  while(WiFi.status() != WL_CONNECTED) {
+    Serial.println("Trying to connect...");
+    delay(1000);  
+  }
+
   Serial.print("Connected with IP: "); Serial.println(WiFi.localIP());
 
   // Connect to the server
-  Serial.println("Connecting to the server...");
+  Serial.print("Connecting to the server: "); 
+  Serial.print(serverAddress); Serial.print(":"); Serial.println(serverPort);
   if (!client.connect(serverAddress, serverPort)) {
     Serial.println("connection failed");
     while(1) delay(1000);