Electronics Blog: wavedrom

Friday, 14 May 2021

WaveDrom with Confluence (Server)

Summary
This blog illustrates how Atlassian's Confluence tool can work with WaveDrom to render scripts. The process requires Confluence Administrator access and a small amount of configuration.

Example of WaveDrom Output

Enabling the HTML Macro
The process of enabling HTML Macro's in Confluence Server is documented in this blog and formally on the Atlassian website here.

The Custom HTML feature is accessed under the Administration 'cog' icon.

Confluence Manage Apps

Open the Manage Apps item. Select System from the drop-down list box. Type HTML into the Filter Visible Apps text box.

Confluence Locate HTML Macro

After typing into the filter, the HTML Macro should be displayed.

Confluence HTML Macro

Expand the Confluence HTML Macro heading.

Confluence HTML Macro Expanded

Then expand the modules enabled heading.

Confluence HTML Macro Enabling

Locate the html (html-xhtml) entry and enable.

This first step is complete.

Custom HTML
To execute a WaveDrom script, the Confluence HTML Macro is processed by custom code added to Confluence pages. The custom code links JavaScript libraries and calls a function to process the WaveDrom script.

Information relating to the libraries is detailed under the Web Usage section of the WaveDrom site on GitHub.

Below is the code taken from the GitHub site.

<script src="https://cdnjs.cloudflare.com/ajax/libs/wavedrom/2.6.8/skins/default.js" type="text/javascript"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/wavedrom/2.6.8/wavedrom.min.js" type="text/javascript"></script>
<body onload="WaveDrom.ProcessAll()">

To add Custom HTML, open the Custom HTML entry under the Look and Feel heading whilst under Confluence Administration.

Confluence Custom HTML

Click Edit.

Confluence Added WaveDrom Link

Under the End of Head section, add the code from the GitHub site.

Confluence Adding WaveDrom

Click Save, this step is completed.

Note that some companies or IT providers may have policies restricting access to external sites.

HTML Macro on Pages with WaveDrom
A script can be generated in the WaveDrom editor then copied into Confluence after it has been finalised or the script can be manually entered into the a HTML macro.

An HTML macro is required to contain the WaveDrom script.

On the required page, use the Insert More Content (Ctrl + Shift + A) to locate the HTML macro. Typing HTML into the Search box will expedite the process.

Confluence Select Macro

Click the HTML then Insert.

Confluence Select Macro Insert

An editable box titled with HTML be displayed.

HTML Macro Inserted into Confluence

The WaveDrom script is then copied into the HTML field.

HTML Macro with WaveDrom Script

Click Update at the bottom of the Confluence page to complete the change.

View the page to ensure the render has worked.

Example of WaveDrom Output

Final Thoughts
Tools such as WaveDrom can provide a permanent description of information such as timing diagrams. Integrating the functionality of WaveDrom into a collaboration tool such as Confluence can reduce the requirement for separate applications and documentation tool consistency.

Saturday, 9 November 2019

Wavedrom for Timing, Documentation and Doxygen

Summary

This post illustrates the benefits of using timing diagram software for debugging and project documentation. Examples of timing software packages used for various purposes include Timing Editor, WaveDrom, Timing Analyser and Waveme.

The implementation in this blog is presented using the JavaScript tool, WaveDrom integrated with Blogger. All credit to the original developer!

Note than the inline Javascript (Wavedrom images) may not execute or display on mobile browsers.

WaveDrom Timing Example
To illustrate a known issue with timing, the input and output states of a controller in a previous blog were used. The timing diagram below captures the power up state, states when a button was pressed then released and lastly the effect of a firmware controlled signal for disabling a hardware output.

The unhandled state was only located after testing however drafting the diagram shows an unhandled state when the firmware controlled signal changes to false. This issue is identified on the timing diagram with the markers a-b and comment 'state'.

For the WaveDrom generated timing diagram shown above, the editor implementation is detailed below.


{signal: 
 [
   {name: 'PSoC Firmware' , wave: '07|.................', node: '....................' },
   {name: 'Control ESTOP' , wave: '05|.............0...', node: '....................' },
   {name: 'ESTOP IN1' , wave: '0.|.5....0....5.....', node: '....................' },
   {name: 'ESTOP IN2' , wave: '0.|.5....0....5.....', node: '....................' },
   {name: 'Contactor'   , wave: '0.|..5....0....5..0.', node: '....................' },
   {name: 'ESTOP LED'   , wave: '0p|...5....n..05....', node: '..................a.b' },
], 
  edge: ['a->b STATE'],
  config:{skin:'default'},
  head: {text: 'ESTOP Controller'}
}

Although the unhandled state was a simple example of timing analysis, it serves to illustrate the benefit of checking logic or drafting timing diagrams.

WaveDrom for Documentation
WaveDrom has an additional feature referred to as Reg which refers to register. This feature can be used for documenting the function of bits in registers.

As an example of the register feature, the communications packet for a Tracer RN series MPPT was extracted from an older blog. Originally the Tracer protocol document was created (updated) in MS Word then published as a PDF for distribution on the web.

Below is an example Tracer RN command packet taken from the protocol document.

Tracer Documentation in MS Word

At the time of writing, WaveDrom does not support a byte representation with the Register feature, however the bit feature can easily be repurposed to represent bytes. Shown below is the same communications packet structure represented in WaveDrom.

For the register that is displayed above, the WaveDrom editor implementation is shown below.

{reg:
[
  {bits: 2,  name: 'End', attr: ['0x7F'], type: 5},
  {bits: 4,  name: 'CRC', attr: ['CRC16', 'x1041','Bits 13:6'], type: 2},
  {bits: 2,  name: 'Ctrl', attr: ['ON = x01', 'OFF = x00'], type: 4},
  {bits: 2,  name: 'Size', attr: 'x01', type: 4},
  {bits: 2,  name: 'Cmd', attr: 'xAA', type: 4},
  {bits: 2,  name: 'Req/Reply', attr: ['Req x01', 'Rep x00'], type: 4},
  {bits: 12,  name: 'Head', attr: ['xEB x90 xEB x90 xEB x90'], type: 5},
], 
  config:{bits: 26}
}

WaveDrom with Doxygen
WaveDrom diagrams and registers can be displayed in the Doxygen generated output using the Doxygen htmlonly special command. This special command can be used in usual source, header and markdown (.md) files.

WaveDrom in Doxygen

Generating the main page output shown above was achieved using the contents of the markdown file detailed below. Doxygen was tweaked to display a navigation tree.


/** @mainpage Register Example
@htmlonly
<script src="https://wavedrom.com/skins/default.js" type="text/javascript"></script>
<script src="https://wavedrom.com/WaveDrom.js" type="text/javascript"></script>
 <script type="WaveDrom">
 {reg:
[
  {bits: 2,  name: 'End', attr: ['0x7F'], type: 5},
  {bits: 4,  name: 'CRC', attr: ['CRC16', 'x1041','Bits 13:6'], type: 2},
  {bits: 2,  name: 'Ctrl', attr: ['ON = x01', 'OFF = x00'], type: 4},
  {bits: 2,  name: 'Size', attr: 'x01', type: 4},
  {bits: 2,  name: 'Cmd', attr: 'xAA', type: 4},
  {bits: 2,  name: 'Req/Reply', attr: ['Req x01', 'Rep x00'], type: 4},
  {bits: 12,  name: 'Head', attr: ['xEB x90 xEB x90 xEB x90'], type: 5},
], 
  config:{bits: 26}
}
 </script> 

<script type="text/javascript">
(function() {
    try {
        WaveDrom.ProcessAll();
    } catch(e) {}
})();
</script>
@endhtmlonly

The structure of the communications register is as detailed above...