added syncWait and get_client_start commands

Synchronization of multiple robots across multiple computers can be challenging. The sync_lib attempts to make that a little easier by providing a convenient library addition. The syncWait() command allows the user to have the sparki wait while giving noop commands so that the connection is maintained. The get_client_start() command provides lower level access to the library.
radarjd · Apr 6, 2017 · b2b8891 · b2b8891
1 parent 218679f
commit b2b8891
Show file tree

Hide file tree

Showing 6 changed files with 86 additions and 19 deletions.
diff --git a/docs/sparki_learning_quick_reference.html b/docs/sparki_learning_quick_reference.html
@@ -362,7 +362,7 @@
 <body>
 <div class="document" id="sparki-learning-command-quick-reference">
 <h1 class="title">Sparki Learning Command Quick Reference</h1>
-<h2 class="subtitle" id="for-version-1-4-0-of-the-python-library">for version 1.4.0 of the python library</h2>
+<h2 class="subtitle" id="for-version-1-4-2-of-the-python-library">for version 1.4.2 of the python library</h2>
 
 <p>(this library makes use of Python 3; Python 2.7 should work, but testing is limited)</p>
 <div class="contents topic" id="contents">
@@ -481,8 +481,10 @@ <h2 class="subtitle" id="for-version-1-4-0-of-the-python-library">for version 1.
 </li>
 <li><a class="reference internal" href="#related-commands" id="id95">Related Commands</a><ul>
 <li><a class="reference internal" href="#synchronization-commands" id="id96">Synchronization Commands</a><ul>
-<li><a class="reference internal" href="#start-sync-server-time-15-server-port-32216" id="id97">start_sync_server(time = 15, server_port = 32216)</a></li>
-<li><a class="reference internal" href="#start-sync-client-server-ip-server-port-32216" id="id98">start_sync_client(server_ip, server_port = 32216)</a></li>
+<li><a class="reference internal" href="#get-client-start-server-ip-server-port-32216" id="id97">get_client_start(server_ip, server_port = 32216)</a></li>
+<li><a class="reference internal" href="#start-sync-server-time-15-server-port-32216" id="id98">start_sync_server(time = 15, server_port = 32216)</a></li>
+<li><a class="reference internal" href="#start-sync-client-server-ip-server-port-32216" id="id99">start_sync_client(server_ip, server_port = 32216)</a></li>
+<li><a class="reference internal" href="#syncwait-server-ip-server-port-32216" id="id100">syncWait(server_ip, server_port = 32216)</a></li>
 </ul>
 </li>
 </ul>
@@ -947,16 +949,26 @@ <h1><a class="toc-backref" href="#id95">Related Commands</a></h1>
 <div class="section" id="synchronization-commands">
 <h2><a class="toc-backref" href="#id96">Synchronization Commands</a></h2>
 <p>The synchronization commands are provided to allow several computers to do something at the same time. In the case of sparki_learning, they are usually used to allow multiple computers to command their respective robots so that the robots can do things together (at the same time). One computer acts as the server, and all other computers act as the clients. The server is told how much time to wait, and then the server communicates that to any clients that connect to the server. When the time expires, the server and clients all return from the synchronization function.</p>
+<div class="section" id="get-client-start-server-ip-server-port-32216">
+<h3><a class="toc-backref" href="#id97">get_client_start(server_ip, server_port = 32216)</a></h3>
+<blockquote>
+Connects to a sync server returns the amount of time before the synchronization event should happen. server_ip should be the server's ip address (which is printed to the server's screen when the server calls start_sync_server()). server_port defaults to 32216 (the same as the server). server_port must be the same on the client and server.</blockquote>
+</div>
 <div class="section" id="start-sync-server-time-15-server-port-32216">
-<h3><a class="toc-backref" href="#id97">start_sync_server(time = 15, server_port = 32216)</a></h3>
+<h3><a class="toc-backref" href="#id98">start_sync_server(time = 15, server_port = 32216)</a></h3>
 <blockquote>
 Starts the sync server to execute the commands following after time seconds. Opens a network socket on the computer, so you may be asked if you want Python to be allowed to open and listen on a port. server_port defaults to port 32216. server_port must be the same on the client and server.</blockquote>
 </div>
 <div class="section" id="start-sync-client-server-ip-server-port-32216">
-<h3><a class="toc-backref" href="#id98">start_sync_client(server_ip, server_port = 32216)</a></h3>
+<h3><a class="toc-backref" href="#id99">start_sync_client(server_ip, server_port = 32216)</a></h3>
 <blockquote>
 Connects to a sync server and executes the commands following after the period of time specified by the server. server_ip should be the server's ip address (which is printed to the server's screen when the server calls start_sync_server()). server_port defaults to 32216 (the same as the server). server_port must be the same on the client and server.</blockquote>
 </div>
+<div class="section" id="syncwait-server-ip-server-port-32216">
+<h3><a class="toc-backref" href="#id100">syncWait(server_ip, server_port = 32216)</a></h3>
+<blockquote>
+Wait for a time specified by a sync server over a network. Uses the <a class="reference internal" href="#get-client-start-server-ip-server-port-32216">get_client_start(server_ip, server_port = 32216)</a> function above.</blockquote>
+</div>
 </div>
 </div>
 </div>

diff --git a/docs/sparki_learning_quick_reference.txt b/docs/sparki_learning_quick_reference.txt
@@ -3,7 +3,7 @@ Sparki Learning Command Quick Reference
 ======================================================
 
 ------------------------------------------------------
-for version 1.4.0 of the python library
+for version 1.4.2 of the python library
 ------------------------------------------------------
 
 (this library makes use of Python 3; Python 2.7 should work, but testing is limited)
@@ -596,6 +596,12 @@ The synchronization commands are provided to allow several computers to do somet
 
 
 
+get_client_start(server_ip, server_port = 32216)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+	Connects to a sync server returns the amount of time before the synchronization event should happen. server_ip should be the server's ip address (which is printed to the server's screen when the server calls start_sync_server()). server_port defaults to 32216 (the same as the server). server_port must be the same on the client and server.
+
+
+
 start_sync_server(time = 15, server_port = 32216)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 	Starts the sync server to execute the commands following after time seconds. Opens a network socket on the computer, so you may be asked if you want Python to be allowed to open and listen on a port. server_port defaults to port 32216. server_port must be the same on the client and server.
@@ -606,3 +612,8 @@ start_sync_client(server_ip, server_port = 32216)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 	Connects to a sync server and executes the commands following after the period of time specified by the server. server_ip should be the server's ip address (which is printed to the server's screen when the server calls start_sync_server()). server_port defaults to 32216 (the same as the server). server_port must be the same on the client and server.
 
+
+
+syncWait(server_ip, server_port = 32216)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+	Wait for a time specified by a sync server over a network. Uses the `get_client_start(server_ip, server_port = 32216)`_ function above. 
diff --git a/setup.py b/setup.py
@@ -7,13 +7,13 @@
 #
 # written by Jeremy Eglen
 # Created: February 24, 2016
-# Last Modified: February 15, 2017
+# Last Modified: April 6, 2017
 # originally written targeting Python 3.4 and 3.5, some testing on 3.6 and has been lightly tested with Python 2.7
 
 from setuptools import setup, find_packages
 setup(
     name = "sparki_learning",
-    version = "1.4.1",
+    version = "1.4.2.5",
     packages = find_packages(),
 
     # Project uses pyserial for bluetooth, so ensure that package gets
@@ -32,7 +32,7 @@
     license = "Apache License Version 2.0",
     keywords = "sparki learning myro robot",
     url = "https://github.com/radarjd/sparki_learning",   # project home page
-    download_url = "https://github.com/radarjd/sparki_learning/tarball/v1.4.0",
+    download_url = "https://github.com/radarjd/sparki_learning/tarball/v1.4.2",
     classifiers = [
                    'Development Status :: 5 - Production/Stable',
                    'Intended Audience :: Education',

diff --git a/sparki_learning/__init__.py b/sparki_learning/__init__.py
@@ -19,7 +19,7 @@
 """
 
 from sparki_learning.sparki_myro import *
-from sparki_learning.sync_lib import start_sync_server, start_sync_client
+from sparki_learning.sync_lib import get_client_start, start_sync_server, start_sync_client
 from sparki_learning.speak import speak
 
 import sparki_learning.sparki_myro
diff --git a/sparki_learning/sparki_myro.py b/sparki_learning/sparki_myro.py
@@ -12,7 +12,7 @@
 #
 # written by Jeremy Eglen
 # Created: November 2, 2015
-# Last Modified: February 15, 2017
+# Last Modified: April 6, 2017
 # Originally developed on Python 3.4 and 3.5; this version modified to work with 3.6; should work on any version >3; limited testing has been successful with Python 2.7
 
 from __future__ import division, \
@@ -40,7 +40,7 @@
 
 ########### CONSTANTS ###########
 # ***** VERSION NUMBER ***** #
-SPARKI_MYRO_VERSION = "1.4.1.1"  # this may differ from the version on Sparki itself and from the library as a whole
+SPARKI_MYRO_VERSION = "1.4.2.3"  # this may differ from the version on Sparki itself and from the library as a whole
 
 # ***** MESSAGE TERMINATOR ***** #
 TERMINATOR = chr(23)  # this character is at the end of every message to / from Sparki
@@ -2610,6 +2610,32 @@ def stop():
     in_motion = False
 
 
+def syncWait(server_ip=None, server_port=32216):
+    """ Wait for a time specified by a sync server over a network
+
+        This function attempts to synchronize multiple computers controlling Sparkis using the sparki_learning.sync_lib library
+        One computer is designated by the programmers as the server. It can, but does not have to, control a sparki itself.
+        The others are designated by the programmers as clients. On the server, you specify an amount of time from now (e.g. 30 seconds)
+        for all clients (and the server) to wait. Each of the clients connects to the server to find out the amount of time to wait.
+        Once the countdown is complete, all the computers stop waiting and execute the rest of the program.
+    
+        arguments:
+        server_ip - string IPv4 address for the program running the server
+                    if none is given to the function, will ask for input
+        server_port - int port to which to connect
+                      if none is given to the function, defaults to 32216
+        
+        returns:
+        nothing
+    """
+    printDebug("In waitForSync, server_ip is " + str(server_ip) + "; server_port is " + str(server_port), DEBUG_INFO)
+
+    from sparki_learning.sync_lib import get_client_start
+    wait_time = get_client_start(server_ip, server_port)
+
+    waitNoop(wait_time)
+
+
 def timer(duration):
     """ Generator which yields the time since the instantiation, and ends after start_time + duration (seconds)
 

diff --git a/sparki_learning/sync_lib.py b/sparki_learning/sync_lib.py
@@ -40,7 +40,6 @@ def _sync_client(server_ip, server_port):
     # The server then sends the time to start the event and both server and client close the socket
     # If the start_time sent by the server is less than 0, this function returns START_NOW
     # Else this function returns the number of seconds between right now and the time that the event is to occur
-
     # receive server's time, return offset, receive start time
     port = int(server_port)
 
@@ -115,6 +114,28 @@ def _sync_server(start_time=START_NOW, port=PORT):
         print(str(client_addr) + " closed")
 
 
+def get_client_start(server_ip=None, server_port=PORT):
+    """ Returns the time the client should start -- specifically:
+        1) connects to a server
+        2) gets the amount of time before which the operation should begin
+
+        arguments:
+        server_ip - string IPv4 address for the program running the server
+                    if none is given to the function, will ask for input
+        server_port - int port to which to connect
+                      if none is given to the function, defaults to 32216
+
+        returns:
+        float - amount of time until the synchronization time
+    """ 
+    if server_ip is None:
+        server_ip = input("What is the server's IP? ")
+
+    wait_time = _sync_client(server_ip, server_port)
+
+    return wait_time
+
+
 def start_sync_client(server_ip=None, server_port=PORT):
     """ Waits for a time specified by a server to return -- specifically:
         1) connects to a server
@@ -130,10 +151,7 @@ def start_sync_client(server_ip=None, server_port=PORT):
         returns:
         nothing
     """
-    if server_ip is None:
-        server_ip = input("What is the server's IP? ")
-
-    wait_time = _sync_client(server_ip, server_port)
+    wait_time = get_client_start(server_ip, server_port)
 
     if wait_time > 0:
         print("waiting " + str(wait_time) + " seconds")
@@ -158,8 +176,8 @@ def start_sync_server(wait_time=15, port=PORT):
     """
     max_wait_time = 24 * 60 * 60  # 60 seconds * 60 minutes * 24 hours = number of seconds in a day
 
-    if wait_time > max_wait_time:  # can't wait more than 24 hours
-        raise RuntimeError("wait time given was more than 24 hours")
+    if wait_time > max_wait_time:  # can't wait more than max_wait_time
+        raise RuntimeError("wait time given was more than " + str(max_wait_time) + " seconds")
 
     start_time = time()
     print("start time is " + str(start_time) + "; wait time is " + str(wait_time) + " seconds")