Merge pull request #1 from robotpy/master

Updating to latest changes

Author: amorygalili

.travis.yml

@@ -0,0 +1,44 @@
+---
+language: python
+services:
+- docker
+
+install:
+- pip install sphinx sphinx-rtd-theme
+
+script:
+- make -C docs html
+- ./build_exe.sh
+
+jobs:
+  include:
+  - stage: format-check
+    python:
+    - "3.6"
+    install:
+    - pip install black
+    script:
+    - black --check --diff .
+
+deploy:
+- provider: pypi
+  user: $PYPI_USERNAME
+  password: $PYPI_PASSWORD
+  on:
+    tags: true
+
+- provider: releases
+  api_key: $GITHUB_OAUTH_TOKEN
+  file_glob: true
+  file: dist/pynetworktables2js*.zip
+  skip_cleanup: true
+  on:
+    tags: true
+
+notifications:
+  webhooks:
+    urls:
+    - https://webhooks.gitter.im/e/2fb1c026e64fdd70d27b
+    on_success: change
+    on_failure: always
+    on_start: never

MANIFEST.in

@@ -1,2 +1,3 @@
+include requirements.txt
 recursive-include example *
 recursive-include pynetworktables2js/js *

README.rst

@@ -1,13 +1,13 @@
 pynetworktables2js
 ==================
 
-A cross platform library that forwards NetworkTables key/values over a Websocket,
+A cross platform library that forwards NetworkTables key/values over a WebSocket,
 so that you can easily write a Driver Station Dashboard for your robot in HTML5 +
 JavaScript.
 
 This library does not provide a full dashboard solution, but is intended to
 provide the necessary plumbing for one to create one with only knowledge
-of HTML/Javascript. Because the communications layer uses NetworkTables, you
+of HTML/JavaScript. Because the communications layer uses NetworkTables, you
 can connect to all FRC languages (C++, Java, LabVIEW, Python).
 
 .. note:: NetworkTables is a protocol used for robot communication in the
@@ -23,6 +23,22 @@ Documentation can be found at http://pynetworktables2js.readthedocs.org/
 Installation
 ============
 
+Easy install (Windows only)
+---------------------------
+
+1. Download the latest pynetworktables2js.exe from GitHub at
+   https://github.com/robotpy/pynetworktables2js/releases .
+2. Extract the exe from the zipfile, and copy it to your directory of HTML/JS
+   files.
+3. Double click the exe to run it!
+
+.. note:: By default, it will connect to 127.0.0.1. To connect to a robot,
+          you will need to pass the exe arguments to tell it where the robot is.
+          Use ``--help`` to see the available options.
+
+Manual install
+--------------
+
 Make sure to install python 2 or 3 on your computer, and on Windows you can
 execute::
 
@@ -56,13 +72,47 @@ those resources to make something cool to control your robot?
 Usage
 =====
 
+You can just distribute your HTML files, and run a pynetworktables server
+using the following command from inside the directory::
+
+    python -m pynetworktables2js
+
+Or on Windows::
+
+    py -m pynetworktables2js
+
+This will start a pynetworktables2js server using Tornado (which is installed
+by default) and it will serve the current directory. You can navigate your
+browser (I recommend Chrome) to http://127.0.0.1:8888 and see your website.
+
+You will want to also pass either the ``--robot`` or ``--team`` switch::
+
+    py -m pynetworktables2js --robot roborio-XXXX-frc.local
+    py -m pynetworktables2js --team XXXX
+
+Dashboard mode currently doesn't work, as the underlying support in
+pynetworktables hasn't been implemented yet for the newer FRC Driver Station.
+
+Customized python server
+------------------------
+
+There are two example servers distributed with pynetworktables2js, one that
+uses `tornado <http://www.tornadoweb.org/en/stable/>`_, and one that uses
+`aiohttp <https://github.com/KeepSafe/aiohttp>`_. Either one should work.
+
 Go to the 'example' directory distributed with pynetworktables2js, and run::
 
-	python server.py --robot 127.0.0.1
+    python tornado_server.py --robot 127.0.0.1
 
 If you want to try this out with your current robot, you can do::
 
-    python server.py --robot roborio-XXX.local
+    python tornado_server.py --robot roborio-XXX.local
+    
+If you are running pynetworktables2js on your driver station laptop, you can
+receive robot IP information directly from the Driver Station (handy during
+actual competitions)::
+
+    python tornado_server.py --dashboard
 
 If you navigate your browser (I recommend Chrome) to http://127.0.0.1:8888, all
 of the current NetworkTables values will be shown as they change.
@@ -77,18 +127,19 @@ dashboard. Just add your custom files to the www directory.
 Contributing new changes
 ========================
 
-pynetworktables2js is intended to be a project that all members of the FIRST
+pynetworktables2js is intended to be a project that all members of the `FIRST`
 community can quickly and easily contribute to. If you find a bug, or have an
 idea that you think others can use:
 
-1. `Fork this git repository <https://github.com/robotpy/pynetworktables2js/fork>`_ to your github account
+1. `Fork this git repository <https://github.com/robotpy/pynetworktables2js/fork>`_
+   to your GitHub account
 2. Create your feature branch (``git checkout -b my-new-feature``)
 3. Commit your changes (``git commit -am 'Add some feature'``)
 4. Push to the branch (``git push -u origin my-new-feature``)
-5. Create new Pull Request on github
+5. Create new Pull Request on GitHub
 
 One place in particular I would love to see contributions is in adding useful
-javascript functions/objects that make creating dashboards even easier!
+JavaScript functions/objects that make creating dashboards even easier!
 
 Authors
 =======

build_exe.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+#
+# Builds a pyinstaller-based Windows exe for pynetworktables2js
+#
+
+cd $(dirname $0)
+docker run --rm -v "$(pwd):/src:Z" -e PYTHONPATH=/src cdrx/pyinstaller-windows:python2
+docker run --rm -v "$(pwd):/src:Z" --entrypoint /bin/bash cdrx/pyinstaller-windows:python2 -c "chown -R $(id -u $USERNAME) /src/dist"
+
+zip dist/pynetworktables2js-$(git describe --tags).zip dist/windows/pynetworktables2js.exe

docs/api_camera.rst

@@ -0,0 +1,50 @@
+JS API: Camera Integration
+==========================
+
+.. code-block:: html
+
+    <script src="/networktables/camera.js"></script>
+    
+.. note:: These functions require `jQuery <http://jquery.com/>`_ to be
+          loaded first!
+
+.. js:function:: loadCameraOnConnect(args)
+
+    This useful helper function will create an img or svg element inside of the
+    div element that you specify. The image will only be connected when a
+    successful NetworkTables connection is detected, to prevent timeout issues.
+    Additionally, this function will attempt to verify that the webcam server is
+    actually up and running before creating the image.
+
+    You should provide an object with an object that can have the following 
+    attributes:
+
+    :param container:   Where to draw things
+    :param proto:       optional, defaults to http://
+    :param host:        optional, if null will use robot's autodetected IP
+    :param port:        optional, webserver port
+    :param image_url:   path to mjpg stream
+    :param data_url:    a file or page that must exist on the webcam server
+    :param wait_img:    optional image to show when not connected
+    :param error_img:   optional image to show when not connected
+    :param attrs:       optional attributes to set on svg or img element
+    :param nosim:       if true, connect to the webcam in simulation mode
+
+    For example, to connect to mjpg-streamer on the RoboRIO:
+    
+    .. code-block:: javascript
+
+        loadCameraOnConnect({
+            container: '#my_div_element',
+            port: 5800,
+            image_url: '/?action=stream',
+            data_url: '/program.json',
+            attrs: {
+                width: 640,
+                height: 480
+            }
+        });
+
+
+    .. note:: This has only been tested with mjpg-streamer, but should work for 
+              other HTTP webcams as well.

docs/api_jquery_ext.rst

@@ -0,0 +1,34 @@
+JS API: JQuery Extensions
+=========================
+
+.. code-block:: html
+
+    <script src="/networktables/jquery_ext.js"></script>
+    
+.. note:: These functions require `jQuery <http://jquery.com/>`_ to be
+          loaded first!
+
+.. js:function:: $.nt_toggle(key, function)
+	
+	When a networktables variable changes, a checkbox element will be updated
+	when a NT variable changes and when a user clicks it.
+
+	Alternatively, you can use this with custom elements, by providing a function
+	that will be called only when the NT value is changed. The NT value will be
+	toggled when the user clicks the selected element(s).
+
+	:param k: Networktables key
+	:param fn: (optional) function that accepts a single param, will be called on change
+	:param evt: (optional) Which event to toggle the value on (defaults to 'click')
+
+	Example usage:
+
+	.. code-block:: javascript
+
+		// this works on a checkbox
+		$('#my_checkbox').nt_toggle('/SmartDashboard/some_boolean');
+
+		// or on a clickable element
+		$('#my_clickable').nt_toggle('/SmartDashboard/b', function(v) {
+			this.css('background-color', v ? 'green' : 'gray');
+		});

docs/api_js.rst

@@ -1,5 +1,13 @@
-JavaScript API
-==============
+JS API: NetworkTables
+=====================
+
+To use these functions, add this to your HTML page:
+
+.. code-block:: html
+
+    <script src="/networktables/networktables.js"></script>
+
+**Note**:
 
 It's very important to note that the Javascript NetworkTables API currently
 has no concept of a table or subtable. When referring to keys when accessing
@@ -35,6 +43,9 @@ These functions allow your code to listen for particular NetworkTables events.
     Sets a function to be called when the robot connects/disconnects to the
     pynetworktables2js server via NetworkTables. It will also be called when
     the websocket connects/disconnects.
+    
+    When a listener function is called with a 'true' parameter, the 
+    NetworkTables.getRobotAddress() function will return a non-null value.
 
     :param f: a function that will be called with a single boolean parameter
               that indicates whether the robot is connected
@@ -93,11 +104,17 @@ NetworkTables Interface
 
     :param key: A networktables key
     :returns: true if a key is present in NetworkTables, false otherwise
+
+    .. warning:: This may not return correct results when the websocket is not
+                 connected
 
 .. js:function:: NetworkTables.getKeys()
 
     :returns: all the keys in the NetworkTables
 
+    .. warning:: This may not return correct results when the websocket is not
+                 connected
+
 .. js:function:: NetworkTables.getValue(key[, defaultValue])
 
     Returns the value that the key maps to. If the websocket is not
@@ -107,10 +124,17 @@ NetworkTables Interface
     :param defaultValue: If the key isn't present in the table, return this instead
     :returns: value of key if present, ``undefined`` or ``defaultValue`` otherwise
 
+    .. warning:: This may not return correct results when the websocket is not
+                 connected
+
     .. note:: To make a fully dynamic webpage that updates when the robot
               updates values, it is recommended (and simpler) to use
               :func:`addKeyListener` or :func:`addGlobalListener` to listen
               for changes to values, instead of using this function.
+              
+.. js:function:: NetworkTables.getRobotAddress()
+
+    :returns: null if the robot is not connected, or a string otherwise
 
 .. js:function:: NetworkTables.isRobotConnected()
 

docs/api_util.rst

@@ -0,0 +1,52 @@
+JS API: Utilities
+=================
+
+To use these functions, add this to your HTML page:
+
+.. code-block:: html
+
+    <script src="/networktables/utils.js"></script>
+
+.. note:: These functions require `jQuery <http://jquery.com/>`_ and
+          `D3 <https://d3js.org/>`_ to be loaded first!
+
+The functions in this file are still experimental in nature, and as we
+expand the number of functions in this file it is expected that the API
+will change.
+
+SendableChooser
+---------------
+
+.. js:function:: attachSelectToSendableChooser(html_id, nt_key)
+
+    Given the id of an HTML ``<select>`` element and the key name of a SendableChooser
+    object setup in networktables, this will sync the select combo box with the
+    contents of the SendableChooser, and you will be able to select an object
+    using the select element.
+
+    :param html_id: An ID of an HTML select element
+    :param nt_key: The name of the NetworkTables key that the SendableChooser
+                   is associated with
+
+    See the WPILib documentation for information on how to use SendableChooser
+    in your robot's program.
+
+.. js:function:: updateSelectWithChooser(html_id, nt_key)
+
+    This function is designed to be used from the onValueChanged callback
+    whenever values from a SendableChooser change, but you probably should
+    prefer to use attachSelectToSendableChooser instead.
+
+    See attachSelectToSendableChooser documentation.
+
+Indicators
+----------
+
+.. js:function:: attachRobotConnectionIndicator(html_id[, size, stroke_width])
+
+    Creates a circle SVG that turns red when robot is not connected, green when
+    it is connected.
+
+    :param html_id: ID to insert svg into
+    :param size: Size of circle
+    :param stroke_width: Border of circle