2019-03-28 Fred Gleason <fredg@paravelsystems.com>

* Added a 'Program Associated Data' chapter to the Operations
	Guide.

ChangeLog

@@ -18555,3 +18555,6 @@
 	* Added a startup check for the 'rivendell' service.
 2019-03-22 Fred Gleason <fredg@paravelsystems.com>
 	* Incremented the package version to 3.0.0rc00.
+2019-03-28 Fred Gleason <fredg@paravelsystems.com>
+	* Added a 'Program Associated Data' chapter to the Operations
+	Guide.

docs/opsguide/Makefile.am

@@ -2,7 +2,7 @@
 ##
 ## docs/opsguide/automake.am for Rivendell
 ##
-## (C) Copyright 2017 Fred Gleason <fredg@paravelsystems.com>
+## (C) Copyright 2017-2019 Fred Gleason <fredg@paravelsystems.com>
 ##
 ##   This program is free software; you can redistribute it and/or modify
 ##   it under the terms of the GNU General Public License version 2 as
@@ -26,6 +26,7 @@ OPSGUIDE_HTML = appendix.filepath_wildcards.html\
                 appendix.rivendell_filter.html\
                 appendix.wings_filter.html\
                 chapter.overview.html\
+                chapter.pad.html\
                 chapter.rdadmin.html\
                 chapter.rdairplay.html\
                 chapter.rdcartslots.html\
@@ -282,6 +283,7 @@ OPSGUIDE_DEPS = $(OPSGUIDE_IMAGES) \
                 opsguide.xml\
                 overview.xml\
                 metadata_wildcards.xml\
+                pad.xml\
                 rdadmin.xml\
                 rdairplay.xml\
                 rdcartslots.xml\

docs/opsguide/opsguide.xml

@@ -2,6 +2,7 @@
 
 <!DOCTYPE book [
   <!ENTITY frontspiece SYSTEM "frontspiece.xml">
+  <!ENTITY pad SYSTEM "pad.xml">
   <!ENTITY overview SYSTEM "overview.xml">
   <!ENTITY rdlogin SYSTEM "rdlogin.xml">
   <!ENTITY rdlibrary SYSTEM "rdlibrary.xml">
@@ -40,6 +41,7 @@
     <title>Rivendell Administration</title>
     &rdadmin;
     &rml;
+    &pad;
     &utilities;
   </part>
   <part xml:id="part.appendices" xmlns="http://docbook.org/ns/docbook" version="5.0">

docs/opsguide/pad.xml

@@ -0,0 +1,194 @@
+<chapter xmlns="http://docbook.org/ns/docbook"  xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="chapter.pad">
+  <title>Program Associated Data</title>
+  <sect1 xml:id="sect.pad.overview">
+    <title>Overview</title>
+    <para>
+      Rivendell includes full support for the origination and transmission
+      of program associated data (PAD) in realtime, including a Python
+      module (PyPAD)
+      that can be used to create scripts for interfacing Rivendell's PAD
+      feed to most any arbitrary external system.
+    </para>
+    <sect2 xml:id="sect.pad.the_json_interface">
+      <title>The JSON Interface</title>
+      <para>
+	All Rivendell PAD updates are emitted as
+	<link xlink:href="https://www.json.org/">JSON documents</link> of
+	type <code>padUpdate</code> via TCP port 34289. A typical update
+	looks like:
+	<programlisting>
+	  <![CDATA[
+{
+    "padUpdate": {
+        "dateTime": "2019-03-28T15:09:01-04:00",
+        "hostName": "elastigirl",
+        "shortHostName": "elastigirl",
+        "machine": 1,
+        "onairFlag": false,
+        "mode": "Automatic",
+        "service": {
+            "name": "Production",
+            "description": "Production Log"
+            "programCode": ""
+        },
+        "log": {
+           "name": "Example"
+        },
+        "now": {
+            "startDateTime": "2019-03-28T15:09:01-04:00",
+            "lineNumber": 0,
+            "lineId": 0,
+            "cartNumber": 10477,
+            "cartType": "Audio",
+            "cutNumber": 1,
+            "length": 225500,
+            "year": null,
+            "groupName": "MUSIC",
+            "title": "Allentown",
+            "artist": "Billy Joel",
+            "publisher": "",
+            "composer": "",
+            "album": "The Complete Hits Collection 1973-1997",
+            "label": "",
+            "client": "",
+            "agency": "",
+            "conductor": "",
+            "userDefined": "",
+            "songId": "",
+            "outcue": "",
+            "description": "Cut 001",
+            "isrc": "",
+            "isci": "",
+            "externalEventId": "",
+            "externalData": "",
+            "externalAnncType": ""
+        },
+        "next": {
+            "startDateTime": "2019-03-28T15:12:46-04:00",
+            "lineNumber": 1,
+            "lineId": 1,
+            "cartNumber": 10153,
+            "cartType": "Audio",
+            "cutNumber": 1,
+            "length": 168700,
+            "year": null,
+            "groupName": "MUSIC",
+            "title": "Me & You & A Dog Named Boo",
+            "artist": "Lobo",
+            "publisher": "",
+            "composer": "",
+            "album": "'70s Radio Hits",
+            "label": "",
+            "client": "",
+            "agency": "",
+            "conductor": "",
+            "userDefined": "",
+            "songId": "",
+            "outcue": "",
+            "description": "Cut 001",
+            "isrc": "",
+            "isci": "",
+            "externalEventId": "",
+            "externalData": "",
+            "externalAnncType": ""
+        }
+    }
+}]]>
+	</programlisting>
+      </para>
+    </sect2>
+
+    <sect2 xml:id="sect.pad.pypad">
+      <title>PyPAD</title>
+      <para>
+	Rivendell ships with a Python 3 module called &quot;pypad&quot; that
+	automates away most of the work involved in reading, parsing and
+	processing the raw JSON data feed described above. A copiously
+	commented example script can be found in the Rivendell source
+	tree at <userinput>apis/pypad/tests/now_and_next.py</userinput>.
+      </para>
+      <sect3 xml:id="sect.pad.pypad.starting_scripts_sutomatically_with_the_rivendell_service">
+	<title>Starting Scripts Automatically with the &quot;rivendell&quot; Service</title>
+	<para>
+	  Rivendell can be configured to start one or more PyPAD scripts
+	  automatically whenever the &quot;rivendell&quot; systemd service
+	  is (re)started. In order to support this, a PyPAD script must
+	  meet the following requirements:
+	</para>
+	<itemizedlist>
+	  <listitem>
+	    <para>
+	      Accept exactly three command-line arguments as follows:
+	    </para>
+	    <para>
+	      <userinput>script <replaceable>host-name</replaceable>
+	      <replaceable>port-num</replaceable>
+	      <replaceable>config</replaceable></userinput>
+	    </para>
+	    <para>
+	      The <replaceable>config</replaceable> value should be
+	      passed to the <code>pypad.Receiver.setConfigFile()</code> method,
+	      and <replaceable>host-name</replaceable> and
+	      <replaceable>port-num</replaceable> values should be
+	      passed to the
+	      <code>pypad.Receiver().start()</code> method.	      
+	      See any of the production PyPAD scripts in the Rivendell
+	      sources in <userinput>apis/pypad/scripts/</userinput> for
+	      an example.
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para>
+	      If the script is configurable via a configuration file,
+	      provide a sample copy of the configuration file, using
+	      wherever possible sane
+	      default values along with comments documenting
+	      what the various parameters do. The file should have the
+	      the same base name as that of the script, but have an
+	      <userinput>.exemplar</userinput> extension.
+	    </para>
+	    <para>
+	      For example, if the script is called
+	      <userinput>myscript.py</userinput>,
+	      the sample configuration file would be called
+	      <userinput>myscript.exemplar</userinput>.
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para>
+	      Install a copy of the script, along with a copy of the
+	      sample configuration file (if needed) in the Rivendell
+	      PyPAD script directory
+	      <userinput><replaceable>$(libdir)</replaceable>/rivendell/pypad/</userinput>.
+	    </para>
+	    <note>
+	      In the RHEL/CentOS reference installation, this directory
+	      is <userinput>/usr/lib64/rivendell/pypad/</userinput>.
+	    </note>
+	    <note>
+	      The <userinput><replaceable>$(libdir)</replaceable></userinput>
+	      path component evaluates to
+	      the value used for the <userinput>--libdir</userinput>
+	      switch that was passed to the &quot;configure&quot; script
+	      when Rivendell was built [default value:
+	      <userinput>/usr/local/lib</userinput>].
+	    </note>
+	  </listitem>
+	</itemizedlist>
+	<para>
+	  All PyPAD scripts started in this manner will be run under the
+	  user/group specified by the <userinput>PypadOwner=</userinput>
+	  and <userinput>PypadGroup=</userinput> directives in the
+	<userinput>[Identity]</userinput> section of the
+	<command>rd.conf</command><manvolnum>5</manvolnum> configuration
+	file.
+	</para>
+	<para>
+	  See <xref linkend="sect.rdadmin.managing_pypad_instances" />
+	  for instructions on enabling a script that has been
+	  prepared in this manner.
+	</para>
+      </sect3>
+    </sect2>
+</sect1>
+</chapter>

docs/opsguide/rdadmin.xml

@@ -2206,7 +2206,14 @@
 	PyPAD is a system that is built into Rivendell that
 	allows processing and transmission of Program Associated Data [PAD]
 	by means of scripts written in the popular Python programming
-	language. To see the list of PyPAD scripts configured to run on
+	language.
+      </para>
+      <note>
+	See <xref linkend="sect.pad.pypad" /> for information
+	on creating your own customized PyPAD scripts.
+      </note>
+      <para>
+	To see the list of PyPAD scripts configured to run on
 	the selected host, touch the 
 	<computeroutput>PyPAD Instances</computeroutput> button to open
 	the PyPAD Instances dialog.
@@ -2260,8 +2267,69 @@
     <para>
       When finished editing the configuration, touch the
       <computeroutput>OK</computeroutput> button to save the configuration
-      and start the script running.
+      and start the script running. The green light adjacent to the entry
+      for the script instance just edited will turn red briefly before
+      turning back to green, indicating that the changes to the configuration
+      have been applied to the active instance.
     </para>
+    <note>
+      It is not necessary to restart rdairplay(1) for the configuration
+      changes to be made effective.
+    </note>
+    <sect3 xml:id="sect.rdadmin.moving_legacy_rlm_configurations_to_pypad">
+      <title>Moving Legacy RLM Configurations to PyPAD</title>
+      <para>
+	Rivendell v2.x included a feature called &quot;Rivendell Loadable
+	Modules&quot; (&quot;RLM&quot; for short) that included much of
+	the functionality now provided by PyPAD. The following RLMs that
+	shipped as part of Rivendell v2.x have been ported to PyPAD
+	and shipped as part of Rivendell 3.x:
+      </para>
+      <simplelist>
+	<member><computeroutput>rlm_ando</computeroutput></member>
+	<member><computeroutput>rlm_filewrite</computeroutput></member>
+	<member><computeroutput>rlm_icecast2</computeroutput></member>
+	<member><computeroutput>rlm_inno712</computeroutput></member>
+	<member><computeroutput>rlm_liqcomp</computeroutput></member>
+	<member><computeroutput>rlm_live365</computeroutput></member>
+	<member><computeroutput>rlm_serial</computeroutput></member>
+	<member><computeroutput>rlm_shoutcast1</computeroutput></member>
+	<member><computeroutput>rlm_spottrap</computeroutput></member>
+	<member><computeroutput>rlm_tunein</computeroutput></member>
+	<member><computeroutput>rlm_udp</computeroutput></member>
+	<member><computeroutput>rlm_urlwrite</computeroutput></member>
+	<member><computeroutput>rlm_walltime</computeroutput></member>
+	<member><computeroutput>rlm_xds</computeroutput></member>
+	<member><computeroutput>rlm_xmpad</computeroutput></member>
+      </simplelist>
+      <para>
+	The formats of the configuration files used for these plug-ins are
+	unchanged under PyPAD. Thus, a &quot;known good&quot; configuration
+	file for an RLM can simply be copy/pasted into the
+	<computeroutput>Configuration</computeroutput> box in the
+	<computeroutput>Edit PyPAD Instance</computeroutput> dialog
+	when setting up its replacement PyPAD script.
+      </para>
+      <caution>
+	Be sure to remove completely the default &quot;sample&quot;
+	configuration entries before copy/pasting in the
+	&quot;known good&quot; ones!
+      </caution>
+      <sect4 xml:id="sect.rdadmin.moving_a_spinitron_rlm_configuration_to_pypad">
+	<title>Moving a Spinitron RLM Configuration to PyPAD</title> 
+	<para>
+	  In addition to the above, some of the functionality of the
+	  <computeroutput>rlm_spinitron_plus</computeroutput> RLM has
+	  been ported into the
+	  <computeroutput>pypad_spinitron</computeroutput> script.
+	  Specifically, support for the deprecated Spinitron v1 interface
+	  has been removed. Sites which have not yet transitioned to
+	  Spinitron v2 will need to do so in order to use this script.
+	  Sites which are already using Spinitron v2 can use their existing
+	  RLM configuration unchanged.
+	</para>
+      </sect4>
+    </sect3>
     </sect2>
   </sect1>
   <sect1 xml:id="sect.rdadmin.manage_system_settings">