RTM_TimerCalc Help

1 post / 0 new
Runtime Micro's picture
Runtime Micro
Offline
Joined: 07/24/2016 - 9:18am
RTM_TimerCalc Help

RTM_TimerCalc is a Windows Desktop application. Its mission is to make easier the creation of C++ code for Arduino Timers. It specifically targets Nano, Uno and Mega2560 MCU boards. Its output code must be copied and pasted into a suitable IDE for compile and upload.

Interface

RTM_TimerCalc presents three main User areas;

  1. Parameters -- selectable presets and several edit areas.
  2. Message Window -- Info, Warnings and Error reporting.
  3. Code Window -- the actual C++ code to copy for your IDE.

Image shows the three main areas of the RTM_TimerCalc interface.

Parameters Area

A blinking prompt guides you to make selections for Clock, Timer and Mode. Selections are limited to Timer Modes that allow variable-Frequency waveforms or variable-Interval Interrupts. Many other Timer modes exist but are not included. This speeds the task of getting a useful result.

A text edit box allows you to enter the wanted Frequency (in Hertz) or Interval (in milliseconds).

Below these items is the WYSIWYG chart. It contains Slider controls for adjusting Waveform Duty-Cycle and Output-Compare modes. As you change these controls, the Waveform display will also change. You get immediate feedback on what to expect after generated code is compiled in your IDE. An oscilloscope connected to pins you targeted should display the same waveforms. Thus the claim for WYSIWYG.

Message Window

Here you'll see information text after the Calculate button is clicked. Some text words may be colored in Blue to grab your attention. You may see all caps headers like; WARNING, ERROR, OFFSET, and NOTE. In nearly all cases, you are being warned of a particular situation that relates to your Parameter choices. Be sure you read the messages and consider whether they affect your intended design. They are there to help you avoid problems and stay on track.

You can not Paste or Edit text in the Message Window.

Code Window

Here the resulting C++ code appears after clicking Calculate. Some code words may be colored blue that tie in with Message-Window warnings. Pay particular attention to such words!

You're expected to Highlight the code sections you want, then Copy-Paste to your IDE for compilation. You may be prevented from performing a Copy if you changed any Parameters after clicking Calculate! A warning pops up in this event and the Calculate button may flash. You must click Calculate again to generate code that reflects your recent changes. In this way, you are stopped from using Code that no longer matches Parameters you recently changed.

The Code-Window contains a context menu you can use to Highlight and Copy code text. You can not Paste or Edit text in the Code Window.

Relevant Arduino Boards and Timers

RTM_TimerCalc targets three (3) popular Arduino MCU boards; Nano, Uno and Mega2560.

Image shows Arduino boards targeted by RTM_TimerCalc.

MCU Timers

Each board MCU has two 8-bit Timers and one or more 16-bit Timers. RTM_TimerCalc targets these Timers as follows;

  • Nano -- Timers (1 and 2)
  • Uno -- Timers (1 and 2)
  • Mega2560 -- Timers (1, 2, 3, 4 and 5)

In all three boards, Timer-2 is an 8-bit with extra Prescale selections. The other Timers are 16-bit with fewer Prescale selections.

NOTE: 8-Bit Timer-0 is never used by RTM_TimerCalc.

Output Channels

The Mega2560 has four 16-bit Timers capable of 3 output waveform channels. In the Nano and Uno, 16-bit Timer-1 has only 2 waveform outputs. In all cases, 8-bit Timer-2 has only 2 possible waveform outputs.

Available Timer Modes

Only a few of the possible Atmel Timer modes are used by RTM_TimerCalc. Each mode was chosen for its wide Frequency or Interval range. This lowers complexity while delivering decent functionality. The Modes break down as follows;

8-Bit Timers

  • Mode-5 Phase PWM
  • Mode-7 Fast PWM

16-Bit Timers

  • Mode-10 Phase PWM
  • Mode-12 CTC Phase shifted Square Waves
  • Mode-14 Fast PWM

Errors and Warnings

As you use the application to solve your Timer design problems, you may encounter certain warning and error messages. They break down as follows;

Error Messages

  • Frequency Out of Bounds: Your parameters or Ask-Frequency result is not possible for the Timer at the current Clock Frequency.
  • Interval Out of Bounds: Your parameters or Ask-Interval result is not possible for the Timer at the current Clock Frequency.
  • OCb not Enabled for OCc to get copy -- You must enable OCb for the 16-bit Timer -or- Un-check the Copy OCb to OCc checkbox. This is a selection only made for Mega2560 MCU boards.

Warning Messages

  • Interrupts without a matching ISR can cause Erratic Operation or Crash! Be certain you have an Interrupt Service Routine (ISR) declared in your code! A prototype of the proper ISR is highlighted in Blue text within the Code-Window. Without an ISR, your Timer Interrupt can wreak havoc on your MCU. You will always see this warning when you check Include Interrupt.
  • Low PWM Resolution. Your /N Value in Code is below 100 -- meaning your PWM Duty-Cycle has steps larger than 1%. If you're using PWM to control a Heater, Motor or something precise, you'll likely need a high PWM resolution. A value of 1% step-size is the bare minimum for matching up with the Duty-Cycle display on the Chart. You will need a lower Waveform Frequency (higher /N) to gain back high Duty-Cycle Resolution.
  • Low Phase Resolution. Your /N Value in Code is below 180 -- meaning your Square-Wave Phase Shift has steps larger than 1 degree. You will need a lower Waveform Frequency (higher /N) to gain back Phase Resolution.
  • Check Parameters -- No Waveform Outputs or Interrupt Selected! You have -neither- Interrupts or Waveforms being generated by the resulting Code. You can still copy-paste the Code if you have plans to use the Timer in some other way.
  • Warning...Offset. The Timer output Frequency will be different from the Ask Frequency. The Offset is the size of this difference. Pay close attention to where the decimal point is on Offset! The difference may be a fraction of a Hertz or up to several Megahertz! Consider carefully if the Offset ruins your intended purpose or not.

Settings

RTM_TimerCalc v1.20 has added more Settings. The previous version Settings are a subset. You can open Settings by clicking the Options-Button on the Toolbar. You can also use the key combination CTRL-ALT-S to open Settings with a wide viewing area. See next image...

To hide the Settings Grid, click the Options-Button again (or use the CTRL-ALT-S key combo again).

Image shows Settings Panel at right side of RTM_TimerCalc application.

One thing to know. Any given Setting will show in Bold-Text when its value is different from its default-value (as when first installed). This makes it easy for Users to spot changed items. The first version of RTM_TimerCalc showed -all- Settings in Bold.

Even though you changed a Setting, you can make it revert to its default value by selecting the Setting and right-click it to see a menu-item "Reset To Default". Click that menu- item to reset your Setting to its default value.

Actions Group Settings

These Settings let you customize what happens under specific circumstances. They are all new in version 1.20;

  • Check for Updates: When set True, the Application checks for a newer version at the Runtime Micro website. If a newer version exists, a Toolbar Button appears at the far right. Click it to go directly to the Latest Release Forum to download. You can change this setting to False if you're concerned about the app. phoning home.
  • Clear On Selections Change: If set True, Message and Code Windows are cleared whenever any non-Chart selection is made.
  • Clear On Sliders Change: If set True, Message and Code Windows are cleared whenever any Chart-Slider is changed.
  • Show Color Text: Allows you to show or hide text coloring in the Message and Code Windows. Its a good idea to leave this set to True unless it bothers you.
  • Text Copy Format: Lets you use one of three text Formats. Its has two plain-text modes and one Rich Text mode. Allows you to match copied text format to nearly any IDE or Editor you may be using. NOTE: If you use Rich-Text-Format, the Arduino-IDE may not recognize Clipboard copied-text as valid! It will seem that Paste isn't functioning. To fix this, use Unicode or Ansi formatted text in Settings selection.

Colors Group Settings

Allows you to customize your viewing experience. May be helpful to adapt to certain Themes or color combinations;

  • Circle Number Color: The Blinking of numbered Parameter labels is intended to guide you through Timer setup steps. It may not look right in your display. You can change the background color to suit...
  • Code Window Color: The Background color of the Code Window. Be warned it always uses the fore-color defined by your Windows Theme.
  • Labels Background: Background color for major section Identifiers such as; Parameters, Code, and Message.
  • Message Window Color: The background color of the Message Window. Be warned it always uses the fore-color defined by your Windows Theme.
  • Property Grid Line Color: The Settings Grid has thin lines delineating the different items shown. You can change the color of these lines to suit your needs.

Fonts Group Settings

  • Chart Duty Font: This new setting lets you control the Duty-Cycle readout in the WYSIWYG Chart. Basically, you can make it bigger and easier to see.
  • Chart Title Font: This new Setting gives you control over the Title and X-axis text areas of the Chart for easier viewing.
  • Code and Message Windows Font: Change how your code and Message window text appears.
  • Labels Font: The font used for app. major area labels (Parameters, Message and Code).
  • Parameters Font: lets you customize text ion that area but be careful to not choose too large a setting. You can break the display. Remember you can revert ta the default setting using a right-click menu.
  • Property Grid Font: This new setting lets you use a larger or smaller font for the Settings Grid.
  • Toolbar Font: Change the size and style of Toolbar Text. This affects the size and style of drop-down menu items too!

Other Features

RTM_TimerCalc v1.20 adds features that can be helpful, especially to those new to Timer coding and Interrupt use.

Code Status Box

Shown just below the WYSIWYG Chart is a small text area that indicates Code Status. The Status indications break down as follows;

  • Gray Background, NOT READY: Indicates you cannot Copy code (if its visible). You need to at least click the Calculate Button. You may need to adjust or select Parameter items.
  • Red Background, ERROR: Indicates something is very wrong. You must evaluate your Parameters, make changes and try again.
  • Yellow Background, WARNING: You can Copy-Paste code but you must decide if you can safely ignore the Warning(s) in the Message Window.
  • Green Background, LOOKS OK: You can Copy-Paste code. The app. detects no problems. There is no guarantee that is the case, though!

Stale Code Copy Prevention

If you attempt to Copy code when the Status-Box indicates Gray or Red, you'll be stopped and told to click the Calculate Button. The button may flash repeatedly. This feature stops you from using code that no longer reflects changes you made. NOTE: even if you set your Actions-Settings to not clear the Code Window after changes are made, this facility still prevents you from using Stale code. This can save you time wondering why compiled code doesn't execute as expected.

Snapshots

Also found in previous version. RTM_TimerCalc lets you take snapshots of the Chart or the entire Application. The snapshot is placed on your Window's O/S Clipboard. Paste it into an email or other Editor. It can be a handy method to generate documentation for a project or to illustrate a problem. Use from the Toolbar drop-down button.