Add developer tools section (#43)

Add a Developer Tools section to the documentation repository.

arednGettingStarted/installing_firmware.rst

@@ -23,7 +23,7 @@ There are two cases for installing AREDN |trade| firmware:
 Ubiquiti First Install Process
 ------------------------------
 
-**Ubiquiti** devices have a built-in `TFTP <https://en.wikipedia.org/wiki/Trivial_File_Transfer_Protocol>`_ server to which you can upload the AREDN |trade| *factory* image. Your computer must have TFTP client software available. Linux and Mac both have native TFTP clients, but you may need to enable or obtain a TFTP client for Windows computers. If you are using a Windows computer, `enable the TFTP client <https://www.trishtech.com/2014/10/enable-tftp-telnet-in-windows-10>`_ or download and install another `standalone TFTP client <http://tftpd32.jounin.net/tftpd32_download.html>`_ of your choice.
+**Ubiquiti** devices have a built-in `TFTP <https://en.wikipedia.org/wiki/Trivial_File_Transfer_Protocol>`_ server to which you can upload the AREDN |trade| *factory* image. Your computer must have TFTP client software available. Linux and Mac both have native TFTP clients, but you may need to enable or obtain a TFTP client for Windows computers. If you are using a Windows computer, `enable the TFTP client <https://www.trishtech.com/2014/10/enable-tftp-telnet-in-windows-10/>`_ or download and install another `standalone TFTP client <http://tftpd32.jounin.net/tftpd32_download.html>`_ of your choice.
 
 Different TFTP client programs may have different command line options or flags that must be used, so be sure to study the command syntax for your TFTP client software. The example shown below may not include the specific options required by your client program.
 

arednHow-toGuides/devtools.rst

@@ -0,0 +1,159 @@
+====================
+Tools for Developers
+====================
+
+This section of the AREDN |trade| documentation contains information useful for developers who want to retrieve information from one or more nodes for use in any of several applications. For example, a developer may want to write a program which periodically polls a set of nodes to gather link quality or signal values to insert them into a network management or historian system for trending and analysis. The popular `KG6WXC MeshMap <https://gitlab.kg6wxc.net/mesh/meshmap>`_ application uses these tools to create and update a comprehensive mesh network map.
+
+SYSINFO.JSON
+============
+
+The **sysinfo.json** `API (Application Programming Interface) <https://en.wikipedia.org/wiki/Application_programming_interface>`_ has been included in AREDN |trade| firmware for several releases, and each release includes an *api_version* tag which can be used to track the feature set supported by that version of the API. As new features are added, the *api_version* number is incremented.
+
+The basic API retrieves general node information in JSON format, and it can be invoked using the following URL:
+``http://<nodename>.local.mesh/cgi-bin/sysinfo.json``
+
+The following information is always returned in the JSON data stream:
+
+* Node name
+* API version
+* Latitude, longitude, and grid square (if available)
+* *Node Details* section containing the firmware manufacturer and version, the radio model and board ID, and the node description text (if any)
+* *Sysinfo* section containing node uptime and load averages for the last one, five, and fifteen minutes
+* *Interfaces* section containing the name, MAC address, and IP address (if any) assigned to each of the node's network interfaces
+* *Mesh RF* section containing the SSID, channel, center frequency, channel width, and status of the mesh radio
+* *Tunnels* section showing whether the tunnel package is installed and the number of active tunnels (if any)
+
+The values returned by the API are represented in the following snippet of raw JSON. This is only a sample of the full data stream containing all of the values described above.
+
+::
+
+  {
+  "api_version": "1.7",
+  "lat": "33.101010",
+  "lon": "-101.101010",
+  "grid_square": "DM22xx",
+  "node": "CALLSIGN-NODE-22",
+  "sysinfo": {
+    "uptime": "5 days, 6:22:30",
+    "loads": [
+      0.05003,
+      0.05003,
+      0
+      ]
+    },
+  "node_details": {
+    "description": "CALLSIGN-22 node information here...",
+    "model": "MikroTik RouterBOARD 952Ui-5ac2nD ",
+    "board_id": "0x0000",
+    "firmware_mfg": "AREDN",
+    "firmware_version": "1101-ad0caaf"
+    }
+  }
+
+In addition to the basic information described above, which is always returned with every invocation, the **sysinfo.json** API can also include other details based on the flags appended to the URL as explained below. In some cases it may be useful to include more than one of the following flags in the URL, and these flags can be combined using the ``&`` operator. For example, ``sysinfo.json?hosts=1&services=1`` will include both the *hosts* and *services* information in addition to the basic details which are always returned.
+
+Add Hosts Information
+---------------------
+
+To retrieve mesh hosts information, invoke the API using the following flag on the URL:
+``http://<nodename>.local.mesh/cgi-bin/sysinfo.json?hosts=1``
+
+A *hosts* section will be included in the JSON data stream containing an entry for each node and mesh-connected device. The *name* and *IP* address of each device will be shown. The values returned by the *hosts* flag are represented in the following snippet of raw JSON.
+
+::
+
+  ...
+  "hosts": [
+    {
+      "name": "CALLSIGN-NODE-22",
+      "ip": "10.22.22.22"
+    },
+    {
+      "name": "CALLSIGN-VOIP-PHONE",
+      "ip": "10.22.22.24"
+    },
+    {
+      "name": "MYCALL-NODE-81",
+      "ip": "10.81.81.81"
+    },
+    {
+      "name": "MYCALL-RPI",
+      "ip": "10.81.81.83"
+    }
+  ],
+  ...
+
+Add Services Information
+------------------------
+
+To retrieve mesh services information, invoke the API using the following flag on the URL:
+``http://<nodename>.local.mesh/cgi-bin/sysinfo.json?services=1``
+
+A *services* section will be included in the JSON data stream containing an entry for each service available on the mesh. Each entry will include the service *name*, *protocol*, and *link* URL. The values returned by the *services* flag are represented in the following snippet of raw JSON.
+
+::
+
+  ...
+  "services": [
+    {
+      "name": "IperfSpeed",
+      "protocol": "tcp",
+      "link": "http:\/\/MYCALL-NODE-81\/iperfspeed"
+    },
+    {
+      "name": "EtherPad",
+      "protocol": "tcp",
+      "link": "http:\/\/MYCALL-RPI:9001\/"
+    },
+    {
+      "name": "MeshChat",
+      "protocol": "tcp",
+      "link": "http:\/\/MYCALL-RPI\/meshchat"
+    }
+  ],
+  ...
+
+Add Local Services Information
+------------------------------
+
+To retrieve information about the services provided only through a single node, invoke the API using the following flag on the URL:
+``http://<nodename>.local.mesh/cgi-bin/sysinfo.json?services_local=1``
+
+A *services_local* section will be included in the JSON data stream containing an entry for each service available through the node being queried. Each entry will include the service *name*, *protocol*, and *link* URL as described above.
+
+Add Link Information
+--------------------
+
+To retrieve mesh link information, invoke the API using the following flag on the URL:
+``http://<nodename>.local.mesh/cgi-bin/sysinfo.json?link_info=1``
+
+A *link_info* section will be included in the JSON data stream containing an entry for each node that is reachable via RF, :abbr:`DTD (Device To Device)`, or :abbr:`TUN (Tunnel)` from the node being queried. Each entry will be identified by the IP address of the reachable node, and within each IP address section you will see the *hostname* (node name), *linkType* (RF, DTD, or TUN), *linkQuality*, *neighborLinkQuality*, *signal*, *noise*, *olsrInterface* name, *tx_rate*, and *rx_rate*. The values returned by the *link_info* flag are represented in the following snippet of raw JSON.
+
+::
+
+  ...
+  "link_info": {
+    "10.22.22.22": {
+      "hostname": "CALLSIGN-NODE-22",
+      "linkType": "RF",
+      "linkQuality": 0.9543000000,
+      "neighborLinkQuality": 0.9748576110,
+      "signal": -76,
+      "noise": -95,
+      "olsrInterface": "wlan0",
+      "tx_rate": 6,
+      "rx_rate": 4
+    },
+    "10.81.106.77": {
+      "hostname": "MYCALL-NODE-81",
+      "linkType": "DTD",
+      "linkQuality": 1,
+      "neighborLinkQuality": 1,
+      "olsrInterface": "eth0.2"
+    }
+  },
+  ...
+
+
+.. |trade|  unicode:: U+00AE .. Registered Trademark SIGN
+   :ltrim:

arednHow-toGuides/puttygen_ssh_keys.rst

@@ -8,7 +8,7 @@ The use of Secure Shell (SSH) keys when using PuTTY or another SSH client is a u
 
 First, obtain the PuTTY suite of applications from the `PuTTY Download Page <https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html>`_ and install them on your computer.
 
-Second, obtain and prepare to use a text editor such as `Notepad++ <https://notepad-plus-plus.org/download/>`_ that does not insert unwanted characters and metadata into a text file.
+Second, obtain and prepare to use a text editor such as `Notepad++ <https://notepad-plus-plus.org/downloads/>`_ that does not insert unwanted characters and metadata into a text file.
 
 Next, follow the steps below.
 

arednServicesGuide/chat_programs.rst

@@ -58,7 +58,7 @@ Mattermost
 
 The *Mattermost Team Edition* is an open source platform that supports mobile and desktop messaging apps. It provides one-to-one and group messaging, file sharing, and message history with search capabilities. It is often described as an open source alternative to the commercial *Slack* communication tool.
 
-Mattermost supports @mentions, and channels are available for organizing conversations which can be topic-based, group-based, or event-based. Notifications indicate user presence and activity. File sharing is provided for PDF and text files, as well as audio, video, and image files. For additional information about Mattermost, visit this link: `Mattermost <https://mattermost.com/>`_
+Mattermost supports @mentions, and channels are available for organizing conversations which can be topic-based, group-based, or event-based. Notifications indicate user presence and activity. File sharing is provided for PDF and text files, as well as audio, video, and image files. For additional information about Mattermost, visit this link: `Mattermost <http://mattermost.com/>`_
 
 .. image:: _images/mattermost.png
    :alt: Mattermost Interface

index.rst

@@ -71,6 +71,7 @@ If you would like to see the documentation for a specific AREDN |trade| release,
    arednHow-toGuides/puttygen_ssh_keys
    arednHow-toGuides/radio_mobile_settings
    arednHow-toGuides/iperf
+   arednHow-toGuides/devtools
 
 .. toctree::
    :maxdepth: 1