Merge pull request #44 from johnrm174/develop

Develop

PUBLIC_API.md

@@ -413,6 +413,9 @@ create_sensor - Creates a sensor object
                              Note that the callback function returns (item_id, callback type)
 
 sensor_active (sensor_id:int) - Returns the current state of the sensor (True/False)
+
+get_list_of_available_ports() - returns a list of supported ports
+
 </pre>
 
 ## Block Instruments
@@ -675,20 +678,6 @@ appropriate level of security. This package does support basic username/password
 for connecting in to the broker but note that these are NOT ENCRYPTED when sending over the 
 internet unless you are also using a SSL connection.
 <pre>
-configure_networking - Configures the local client and opens a connection to the MQTT broker
-                   Returns whether the connection was successful (or timed out)
-                   NOTE THAT THE 'CONFIGURE_NETWORKING' FUNCTION IS NOW DEPRECATED
-                   Use the 'configure_mqtt_client' and 'mqtt_broker_connect' functions instead
-  Mandatory Parameters:
-      broker_host:str - The name/IP address of the MQTT broker host to be used
-      network_identifier:str - The name to use for this signalling network (any string)
-      node_identifier:str - The name to use for this node on the network (can be any string)
-  Optional Parameters:
-      broker_port:int - The network port for the broker host (default = 1883)
-      broker_username:str - the username to log into the MQTT Broker (default = None)
-      broker_password:str - the password to log into the MQTT Broker (default = None)
-      mqtt_enhanced_debugging:bool - 'True' to enable additional debug logging (default = False)
-
 configure_mqtt_client - Configures the local MQTT client and layout network node
   Mandatory Parameters:
       network_identifier:str - The name to use for this signalling network (any string)
@@ -714,7 +703,70 @@ subscribe_to_dcc_command_feed - Subcribes to DCC command feed from another node
   Mandatory Parameters:
       *nodes:str - The name of the node publishing the feed (multiple nodes can be specified)
 
-subscribe_to_section_updates - Subscribe to section updates from another node on the network 
+subscribe_to_remote_section - Subscribes to a remote track section object
+  Mandatory Parameters:
+      remote_identifier:str - the remote identifier for the track section in the form 'node-id'
+  Optional Parameters:
+      section_callback - Function to call when a track section update is received  - default = None
+
+set_sections_to_publish_state - Enable the publication of state updates for track sections.
+               All subsequent changes will be automatically published to remote subscribers
+  Mandatory Parameters:
+      *sec_ids:int - The track sections to publish (multiple Section_IDs can be specified)
+
+subscribe_to_remote_signal - Subscribes to a remote signal object
+  Mandatory Parameters:
+      remote_identifier:str - the remote identifier for the signal in the form 'node-id'
+  Optional Parameters:
+      signal_callback - Function to call when a signal update is received - default = None
+
+set_signals_to_publish_state - Enable the publication of state updates for signals.
+               All subsequent changes will be automatically published to remote subscribers
+  Mandatory Parameters:
+      *sig_ids:int - The signals to publish (multiple Signal_IDs can be specified)
+
+subscribe_to_remote_instrument - Subscribes to a remote block instrument object
+  Mandatory Parameters:
+      remote_identifier:str - the remote identifier for the block instrument in the form 'node-id'
+
+set_instruments_to_publish_state - Enable the publication of state updates for block instruments.
+               All subsequent changes will be automatically published to remote subscribers
+  Mandatory Parameters:
+      *inst_ids:int - The block instruments to publish (multiple Instrument_IDs can be specified)
+
+subscribe_to_remote_sensor - Subscribes to a remote track sensor object
+  Mandatory Parameters:
+      remote_identifier:str - the remote identifier for the sensor in the form 'node-id'
+  Optional Parameters:
+      signal_passed:int    - Raise a "signal passed" event for a signal ID - default = None
+      signal_approach:int  - Raise an "approach release" event for a signal ID - default = None
+      sensor_callback      - Function to call when a sensor has been triggered - default = None
+                             Only one of signal_passed, signal_approach or callback can be specified
+                             Note that for callback, the function returns (item_id, callback type)
+
+set_sensors_to_publish_state- Enable the publication of state updates for track sensors.
+             All subsequent changes will be automatically published to remote subscribers
+  Mandatory Parameters:
+      *sensor_ids:int - The track sensors to publish (multiple Sensor IDs can be specified)      
+
+THE FOLLOWING FUNCTIONS ARE DEPRECATED:
+
+configure_networking - Configures the local client and opens a connection to the MQTT broker
+                   Returns whether the connection was successful (or timed out)
+                   NOTE THAT THE 'CONFIGURE_NETWORKING' FUNCTION IS NOW DEPRECATED
+                   Use the 'configure_mqtt_client' and 'mqtt_broker_connect' functions instead
+  Mandatory Parameters:
+      broker_host:str - The name/IP address of the MQTT broker host to be used
+      network_identifier:str - The name to use for this signalling network (any string)
+      node_identifier:str - The name to use for this node on the network (can be any string)
+  Optional Parameters:
+      broker_port:int - The network port for the broker host (default = 1883)
+      broker_username:str - the username to log into the MQTT Broker (default = None)
+      broker_password:str - the password to log into the MQTT Broker (default = None)
+      mqtt_enhanced_debugging:bool - 'True' to enable additional debug logging (default = False)
+
+subscribe_to_section_updates - Subscribe to section updates from another node on the network
+      NOTE THAT THIS FUNCTION IS NOW DEPRECATED - use 'subscribe_to_remote_track_section' instead
   Mandatory Parameters:
       node:str - The name of the node publishing the track section update feed
       sec_callback:name - Function to call when an update is received from the remote node
@@ -723,6 +775,7 @@ subscribe_to_section_updates - Subscribe to section updates from another node on
       *sec_ids:int - The sections to subscribe to (multiple Section_IDs can be specified)
 
 subscribe_to_signal_updates - Subscribe to signal updates from another node on the network 
+      NOTE THAT THIS FUNCTION IS NOW DEPRECATED - use 'subscribe_to_remote_signal' instead
   Mandatory Parameters:
       node:str - The name of the node publishing the signal state feed
       sig_callback:name - Function to call when an update is received from the remote node
@@ -731,38 +784,27 @@ subscribe_to_signal_updates - Subscribe to signal updates from another node on t
       *sig_ids:int - The signals to subscribe to (multiple Signal_IDs can be specified)
 
 subscribe_to_signal_passed_events  - Subscribe to signal passed events from another node  
+    NOTE THAT THIS FUNCTION IS NOW DEPRECATED - only pub/subscribe to signal state will be
+    supported from release 4.0.0 (use track sections to achieve the required functionality)
   Mandatory Parameters:
       node:str - The name of the node publishing the signal passed event feed
       sig_callback:name - Function to call when a signal passed event is received
                Callback returns (item_identifier, sig_callback_type.sig_passed)
                Item Identifier is a string in the following format "node_id-signal_id"
       *sig_ids:int - The signals to subscribe to (multiple Signal_IDs can be specified)
 
-subscribe_to_instrument_updates - Subscribe to instrument updates from another node on the network 
-  Mandatory Parameters:
-      node:str - The name of the node publishing the block instrument update feed
-      *inst_ids:int - The instruments to subscribe to (multiple Instrument_IDs can be specified)
-
-set_sections_to_publish_state - Enable the publication of state updates for track sections.
-               All subsequent changes will be automatically published to remote subscribers
-  Mandatory Parameters:
-      *sec_ids:int - The track sections to publish (multiple Section_IDs can be specified)
-
-set_signals_to_publish_state - Enable the publication of state updates for signals.
-               All subsequent changes will be automatically published to remote subscribers
-  Mandatory Parameters:
-      *sig_ids:int - The signals to publish (multiple Signal_IDs can be specified)
-
 set_signals_to_publish_passed_events - Enable the publication of signal passed events.
+    NOTE THAT THIS FUNCTION IS NOW DEPRECATED - only pub/subscribe to signal state will be
+    supported from release 4.0.0 (use track sections to achieve the required functionality)
                All subsequent events will be automatically published to remote subscribers
   Mandatory Parameters:
       *sig_ids:int - The signals to publish (multiple Signal_IDs can be specified)
-      
-set_instruments_to_publish_state - Enable the publication of state updates for block instruments.
-               All subsequent changes will be automatically published to remote subscribers
+
+subscribe_to_instrument_updates - Subscribe to instrument updates from another node on the network
+      NOTE THAT THIS FUNCTION IS NOW DEPRECATED - use 'subscribe_to_remote_instrument' instead
   Mandatory Parameters:
-      *inst_ids:int - The block instruments to publish (multiple Instrument_IDs can be specified)
-
+      node:str - The name of the node publishing the block instrument update feed
+      *inst_ids:int - The instruments to subscribe to (multiple Instrument_IDs can be specified)
 </pre>
 
 ## Code examples

README.md

@@ -21,20 +21,22 @@ What's currently supported by the Editor:
 * Configure GPIO sensors and track sections to provide a 'mimic' display of the layout
 * Configure a level of automation for the signals as trains traverse the layout
 
-What's new in Release 3.5:
-* MQTT networking - large layouts with multiple signalling areas can be split across multiple platforms
-  * Simple configuration for connecting to a local (you'll have to stand-up) or internet-based MQTT broker
-  * Publish and subscribe to signals, track sections and block instruments from each application instance
-  * Publish and subscribe to DCC feeds - allows multiple applications to share the same R-Pi/Pi-SPROG
+What's new in Release 3.6:
+* MQTT Publish/subscribe for track sensors - allows remote applications to use the R-Pi's GPIO sensors
+* Minor bugfixes and application enhansements to (hopefully) improve the overall user experience
+* Consolidation of library functions (if anyone out there is still using the API to write their own code)
 
 What's coming soon:
-* MQTT publish and subscribe to GPIO ports - for signal-passed and signal-approached events
-* Text boxs - Ability to add and edit text boxes on the schematic
+
+* Release 4.0 (where I'm going to rip out all the deprecated functions) - you have been warned
+* Text boxes - Ability to add/edit text boxes on the schematic to annotate your layout
+* Toggle automation - for those occasions you just want to watch the trains go by
 
 Any bug reports and feedback you may have would be gratefully appreciated - specifically:
 * What aspects are intuitive? What aspects aren't?
 * What aspects do you particularly like?
 * What aspects particularly irritate you?
+* What new features would you like to see?
 
 There are some example layout files in the 'configuration_examples' folder.
 

code_examples/test_block_instruments.py

@@ -48,10 +48,11 @@ def process_callbacks(item_id,callback_type):
 create_block_instrument(canvas, 3, 150, 300, linked_to = 4,
                       bell_sound_file='bell-ring-03.wav',
                       block_callback=process_callbacks,
-                      single_line = True )
+                      inst_type = instrument_type.single_line)
 create_block_instrument(canvas, 4, 450, 300, linked_to = 3,
                       bell_sound_file='bell-ring-04.wav',
-                      single_line = True )
+                      block_callback=process_callbacks,
+                      inst_type = instrument_type.single_line)
 create_block_instrument(canvas, 5, 150, 600, linked_to = "Box2-1")
 
 print ("Entering Main Event Loop")

code_examples/test_networking_1.py

@@ -22,7 +22,7 @@
 # the messages being published to external nodes via the MQTT Broker
 #----------------------------------------------------------------------
 
-logging.basicConfig(format='%(levelname)s: %(message)s',level=logging.DEBUG) 
+logging.basicConfig(format='%(levelname)s: %(message)s',level=logging.INFO) 
 
 # There is an additional level of debug logging that can be enabled for the MQTT interface
 # This will show the log messages being generated by the Client for published/received messages
@@ -136,13 +136,14 @@ def lower_line_callback(item_id,callback_type):
 print ("Initialising MQTT Client and connecting to external Broker")
 # Configure the MQTT Broker networking feature to allow this application node to act as a remote
 # DCC command station for other application nodes (i.e. forward received DCC commands to the Pi-Sprog) 
-configure_networking(broker_host ="broker.emqx.io", network_identifier="network1", broker_port=1883,
-                     node_identifier= "Box1", mqtt_enhanced_debugging=mqtt_debug )
+configure_mqtt_client(network_identifier="network1", node_identifier= "Box1", enhanced_debugging=mqtt_debug)
+mqtt_broker_connect(broker_host ="broker.emqx.io", broker_port=1883)
 # Configure the events/updates we want to publish/subscribe to
 set_sections_to_publish_state(3,9,12)
 set_instruments_to_publish_state(1,2)
 set_signals_to_publish_passed_events(1,7,10)
 set_signals_to_publish_state(1)
+set_track_sensors_to_publish_state(13,14,15,16)
 subscribe_to_section_updates("Box2",upper_line_callback,3)
 subscribe_to_signal_passed_events("Box2",upper_line_callback,1)
 subscribe_to_signal_updates("Box2",upper_line_callback,1)
@@ -154,6 +155,8 @@ def lower_line_callback(item_id,callback_type):
 # Note the lack of a callback when subscribing to instrument events
 subscribe_to_instrument_updates("Box2",2)
 subscribe_to_instrument_updates("Box2",1)
+# Track Sensors
+set_track_sensors_to_publish_state(4,5,6)
 
 print ("Drawing Layout Schematic")
 canvas.create_line(0,150,750,150,fill="black",width=3) 
@@ -170,6 +173,14 @@ def lower_line_callback(item_id,callback_type):
                                  "on the TELEGRAPH button to bring up a list of bell codes" )
 canvas.create_text (650,430,text="Box 2 ===>>")
 
+print ("Creating local track Sensors")
+create_track_sensor (1,gpio_channel=4,sensor_timeout=1.0,signal_passed=1)
+create_track_sensor (2,gpio_channel=5,sensor_timeout=1.0,signal_passed=2) 
+create_track_sensor (3,gpio_channel=6,sensor_timeout=1.0,signal_passed=3)
+create_track_sensor (4,gpio_channel=7,sensor_timeout=1.0)
+create_track_sensor (5,gpio_channel=8,sensor_timeout=1.0) 
+create_track_sensor (6,gpio_channel=9,sensor_timeout=1.0)
+
 print ("Creating track Occupancy Sections")
 # Upper Line Sections
 # Section 100 is an non editable section to show the next approaching train

code_examples/test_networking_2.py

@@ -131,9 +131,9 @@ def lower_line_callback(item_id,callback_type):
 
 print ("Initialising MQTT Client and connecting to external Broker")
 # Configure the MQTT Broker networking feature to allow this application node to act as a remote
-# DCC command station for other application nodes (i.e. forward received DCC commands to the Pi-Sprog) 
-configure_networking(broker_host ="broker.emqx.io", network_identifier="network1", broker_port=1883,
-                                 node_identifier= "Box2", mqtt_enhanced_debugging=mqtt_debug)
+# DCC command station for other application nodes (i.e. forward received DCC commands to the Pi-Sprog)
+configure_mqtt_client(network_identifier="network1", node_identifier= "Box2", enhanced_debugging=mqtt_debug)
+mqtt_broker_connect(broker_host ="broker.emqx.io", broker_port=1883)
 # Configure the events/updates we want to publish/subscribe to
 set_sections_to_publish_state(3,9,12)
 set_instruments_to_publish_state(1,2)
@@ -147,9 +147,13 @@ def lower_line_callback(item_id,callback_type):
 subscribe_to_signal_passed_events("Box1",middle_line_callback,7)
 subscribe_to_section_updates("Box1",lower_line_callback,12)
 subscribe_to_signal_passed_events("Box1",lower_line_callback,10)
-# Note the lack ofr a callback when subscribing to instrument events
+# Note the lack of a callback when subscribing to instrument events
 subscribe_to_instrument_updates("Box1",2)
 subscribe_to_instrument_updates("Box1",1)
+# Track Sensors
+subscribe_to_remote_track_sensor("Box1-4",signal_passed=1)
+subscribe_to_remote_track_sensor("Box1-5",signal_passed=2)
+subscribe_to_remote_track_sensor("Box1-6",signal_passed=3)
 
 print ("Drawing Layout Schematic")
 canvas.create_line(0,150,750,150,fill="black",width=3)