Merge pull request #106 from open-ephys/issue-89

Add content on why port status is helpful

Author: cjsha

template/partials/hardware/portStatus.tmpl.partial

@@ -1,20 +1,36 @@
 <p>
-  The following excerpt from the {{{hardware}}} <a class="xref" href="~/articles/hardware/{{{oe.hardwareDirectory}}}/overview.html">example workflow</a> demonstrates port status functionality and saves timestamped port status data.
+  The Onix system reports when a headstage port connection enters or leaves an aberrant state. Such aberrant states include loss
+  of communication lock, detection of parity or CRC error, reception of a badly formatted packet, etc.. Knowing the time
+  and type of a communication failure is a good first step to track down its cause. The following excerpt from the
+  {{{hardware}}} <a class="xref" href="~/articles/hardware/{{{oe.hardwareDirectory}}}/overview.html">example
+  workflow</a> demonstrates port status functionality and saves timestamped port status data.
 </p> 
 
 <div class="workflow"> 
   <p><img src="~/workflows/{{{oe.path}}}.bonsai" alt="~/workflows/{{{oe.path}}}.bonsai workflow"></p>
 </div>
 
 <p>
-  The {{{hardware}}} reports when a port connection enters or leaves an aberrant state via the <a class="xref" href="~/api/OpenEphys.Onix1.PortStatus.html">PortStatus</a> operator, which generates a sequence of <a class="xref" href="~/api/OpenEphys.Onix1.PortStatus.html">PortStatusFrame</a>s. Events that cause the <code>PortStatus</code> to emit a <code>PortStatusFrame</code> include the SERDES losing or gaining lock, SERDES failing or passing parity check, or the <a class="xref" href="~/api/OpenEphys.Onix1.PortStatusCode.html">PortStatusCode</a> changing value. The <code>DeviceName</code> is set to "{{{hardwareOperator}}}/PortController". This links the <code>PortStatus</code> operator to the corresponding configuration operator.
+  Headstage port status data is produced in Bonsai by the <a class="xref"
+  href="~/api/OpenEphys.Onix1.PortStatus.html">PortStatus</a> operator which generates a sequence of <a class="xref"
+  href="~/api/OpenEphys.Onix1.PortStatusFrame.html">PortStatusFrames</a>. <code>PortStatus</code> emits a
+  <code>PortStatusFrame</code> whenever <a class="xref"
+  href="~/api/OpenEphys.Onix1.PortStatusCode.html">PortStatusCode</a> changes value. <code>PortStatus</code>'s
+  <code>DeviceName</code> property is set to "{{{hardwareOperator}}}/PortController". This links the
+  <code>PortStatus</code> operator to the breakout board's port controller.
 </p>
 
 <p>
-  The <a class="xref" href="https://bonsai-rx.org/docs/api/Bonsai.Reactive.Timestamp.html">TimeStamp</a> operator generates a sequence of timestamped items from its input sequence. The <a class="xref" href="https://bonsai-rx.org/docs/api/Bonsai.IO.CsvWriter.html">CsvWriter</a> operator writes <code>Timestamp</code> as well as <code>Clock</code>, <code>StatusCode</code>, <code>SerdesLocked</code>, and <code>SerdesPass</code> members from <code>PortStatusFrame</code> to a file with the following name format: <code>port-status_&lt;timestamp&gt;.csv</code>.
+  The <a class="xref" href="https://bonsai-rx.org/docs/api/Bonsai.Reactive.Timestamp.html">TimeStamp</a> operator
+  generates a sequence of UTC timestamped items from its input sequence. The <a class="xref"
+  href="https://bonsai-rx.org/docs/api/Bonsai.IO.CsvWriter.html">CsvWriter</a> operator writes <code>Timestamp</code> as
+  well as <code>Clock</code> and <code>StatusCode</code> members from <code>PortStatusFrame</code> to a file with the
+  following name format: <code>port-status_&lt;timestamp&gt;.csv</code>.
 </p>
 
 <div class="NOTE alert alert-info">
   <h5>NOTE</h5>
-  <p>The <code>PortStatus</code> datastream is always enabled. <code>{{{configureHardwareOperator}}}</code> has no <code>Enable</code> property for the <code>PortStatus</code> operator like other Data I/O operators that can be used with the {{{hardware}}}.</p>
+  <p>The <code>PortStatus</code> datastream is always enabled. <code>{{{configureHardwareOperator}}}</code> has no
+  <code>Enable</code> property for the <code>PortStatus</code> operator like other Data I/O operators that can be used
+  with the {{{hardware}}}.</p> 
 </div>