BUTTONS

Introduction

The button is probably the most common and certainly one of the most versatile controls in the IoT Control Library. This topic discusses the different types of button and various configuration options but the basic process for adding a button is the same in all cases.

To add a button

1) Right click on the Arduino Yun in the project tree and select the Add IoT Control command from the resulting context menu

2) Make sure the category selector shows buttons and choose your theme from the selector on the right.

The theme determines the available styles of buttons but not their functionality and lets you create a modern looking GUI or a classic retro panel according to your preference.

3) There may be three types of button, namely radio buttons, icon buttons and standard buttons.

  • Radio buttons are a mutually exclusive option group which you can easily query to see which option is selected. If you want radio buttons select the button type and the number of elements and then click to add.
  • Icon buttons are normal buttons pre-loaded with a selectable icon such as power, play, stop, etc. If you want an icon button just click to select and then click the add button to bring it into your project.
  • Standard buttons are all of the other buttons and may come in different shapes and styles. If you want a standard button follow the usual steps of click to select and then add button to bring into your project.

Design Time Configuration

Configuration of the buttons can be done primarily at design time once the button is placed on the panel. We'd suggest you first rename your button to suit it's purpose, then double click on the Mains Control panel to show and finally drag and drop the button control onto the panel.

Renaming and placing a button

Select the button by left clicking on it and then view the properties in the property pane at the bottom left of your editor.

Button properties

The following properties are commonly available:

Geometry Properties (x, y, width, height)

These properties enable positioning and aligment. For example you could set a series of controls to have the same x value to align them vertically, The width and height properties allow for sizing of the control, although you may find it just as easy to use the 'restore aspect ratio' command on the right click context menu for the control after sizing with the mouse.

Mode Property

There are three types of button:

  • One-Click Mode : The button has a single state (clicked). Your event handler in the firmware is called after the click is completed.
  • Momentary Action : The button can be depressed and held down (the momentary action) but will return to it's default state on release. Your event handler in the firmware is called when the button is depressed and again when it is released.
  • Toggle : A binary button with two states (e.g. on and off) which are toggled on click. Your event handler in the firmware is called whenever the button is clicked and you can use the getState() method to query whether state is 1 or 0.

The choice of button mode depends on what you want to happen when you press the button. If for example you have a reset button then you would have a one-click button because each time you press that button you want to reset the app. If you want to turn the volume up you might use a momentary action button which will respond while the button is depressed. If you want to toggle something on and off then you want to use a toggle button because you can query the state of the button at any time.

autoLamp Property

The buttons all have a lamp indicator ring which can be illuminated when they are pressed/active. This provides useful visual feedback on the UI device and can be automated via this property. The behaviour of the autolamp property depends on the type of button chosen as follows:

  • One-Click Button : The lamp indicator will come on when the button is depressed and go off when the button is released.
  • Momentary Action Button : The lamp indicator will come on when the button is depressed and go off when the button is released.
  • Toggle Button : The lamp indicator will come on when the button is clicked and will stay on until the button is clicked again.

It follows that using the autoLamp property makes the most sense when you have a toggle button because the lamp indicator can automatically reflect an on and off state. The default behaviour however is to have autolamp turned off because a more complete approach to setting the lamp indicator is to do so explicitly in your program via the setLamp() method.

setLamp() method

The benefit of this is that it is the firmware running on the appliance that dictates the state of the lamp which is then guaranteed correct. While it is very convenient to use the autolamp property here be aware that it will work with no interaction with your appliance (i.e. entirely in the GUI).

Icon Property (only available with Icon buttons !)

If you have chosen to use an icon button then you can specify which icon to use from a pre-selected list or - with some effort - you can add a custom icon of your own.

To add a custom icon you will need to edit the SVG file natively. This is not a trivial operation but the process is discussed in some detail here.

Label Configuration

These properties are all fairly self-explanatory, allowing you to enter label text, position the label relative to the control and then control the spacing of the label from the control. You can also choose from a small selection of font types and set font size, decorations and colours.

Lamp Colour

Specify the colour of the indicator lamp on the button. This is used when you execute the setLamp() method in your program or if you set the autolamp property to be true.

Face Colour

Specify the colour of the button face, excluding the lamp indicator ring.

Programming Methods

Having configured the buttons we still need to access them in our program. There are three available methods (only two for radio buttons) which we can see by dropping the tree down a level in the project tree.

All 3 possible methods

Depending on what product you have these methods can be dragged and dropped into your flowchart program (as a method call block) or into your source code project (as a skeleton function).

setState() Method

The setState() Method applies only to the toggle button type (because that is the only type that has two states) and allows you to set a pre-defined state without executing an actual button press. For example, if you had a logging button which you had set to be of type toggle (on and off) then you might decide that the default behaviour should be to log data. In this case you would use the setState() method in your setup routine so that your appliance was logging and the first user press of the button served to disable logging.

See Also:

Mode Property

getState() Method

The getState() method again applies only to the toggle button and returns the current state of the button as a boolean.

setLamp() Method

The setLamp() method serves to turn on or off the indicator lamp on the button. This is intended for use when the autoLamp property is set to false and allows the firmware to control the feedback to the user on the controller.

If instead you use the autoLamp property then you don't need to use this method at all but the indicator on the users panel will simply toggle, irrespective of whether the button press command is received and processed successfully.


SWITCHES

Introduction

Depending on which theme you choose there are three possible types of switches:

  • Simple two state switches (flick switches, toggle switches etc.)
  • Slide switches (multi-state)
  • Rotary switches (multi-state)

To add a switch

1) Right click on the Arduino Yun in the project tree and select the Add IoT Control command from the resulting context menu

2) Make sure the category selector shows Switches and choose your theme from the selector on the right.

3) Either double click on the switch to add it directly or click to select and then press the add button to add it to the project.

Design Time Configuration

The first thing to do is to rename the switch to reflect it's purpose in your design. You can do this via the right click context menu.

To place the switch on your panel first open the panel editor by double clicking on the IoT 'Main Control' Panel in Project Tree. Next, drag and drop the switch onto the panel and position as required.

To configure the behaviour of the switch select it on the panel and then adjust the properties in the property editor pane.

Toggle Switch

The toggle switch has geometry configuration allowing to precisely size the control using width and height fields and also to align with other controls by applying a common x or y value.

It also includes two labels which allows you to add descriptive text for both states of the switch (e.g. on and off )

You can also change the orientation between vertical and horizontal and specify a spacing for the labels from the control body.

It is much better to set this property than to rotate the control because the text labels will position themselves correctly when you adjust with the property.

Finally, you can configure the font size and font type for the text labels via the labelFont properties.

Rotary Switch

In addition to the properties for toggle switch the rotary switch contains additional configuration for the multiple states:

The init property lets you set the state at which the dial should start, the numStates property defines how many states the switch will have and the amin/amax properties define the angle range for the dial. For the angles, consider straight up to be angle=0, left is negative and right is positive. So for example amin=-90 and amax=90 uses the top half of the dial.

We also have some more aesthetic properties for specifying the length of the little ticks leading out of the dial (tickLength), changing their colour (tickColour) and for disabling them altogether (showTicks), along with the tickLabels property to change the text of the labels as a comma separated list or choose to hide the labels (showLabels).

Slide Switch

The slide switch is very similar to the rotary switch. It has the basic set of properties we saw in the toggle switch, including the orientation property which allows us to set the bar either vertically or horizontally. There are then a couple more properties related to label positioning. You can choose to position to the right if vertical which will then be below if horizontal or you can choose to position to the left if vertical which will position above when the orientation is horizontal.

The movement and positioning of the labels will work properly only if you change the orientation of the control via this property. Rotating the control will not adjust the labels.

You can also choose to stagger the labels onto two rows which can make it much easier to make text readable with horizontal orientation.

Programming Methods

The programming methods allow us to access and control the peripheral at run time. For the switch there are only two methods, namely getState() and setState().

getState() Method

Reads the value of the switch position as an integer value starting from 0. eg a toggle switch has two states 0 and 1. A slide switch could have multiple in the format of 0,1,2,3..... with 0 being the bottom most state. A rotary switch has a 0 state on the location furthest in the negative degree direction.

setState() Method

Programmatically changes the state of the switch and causes the control to move to indicate the new condition.


DISPLAYS

Introduction

There are basically six types of display controls that you can select:

  • Moving dial controls (e.g. panel meter, speedometer).
  • 7-Seg display control
  • Mercury thermometer control
  • Loading / Percentage bar.
  • LED Strip
  • Gauge

To add a display control

1) Right click on the Arduino Yun in the project tree and select the Add IoT Control command from the resulting context menu

2) Make sure the category selector shows Display Controls and choose your theme from the selector on the right.

3) If you are adding a moving dial control or a thermometer you simply click to select and then press the add button to add it to the project.

If you are adding a 7 segment display then you need to select the control, specify the number of elements at the bottom and then add it to the project.

Design Time Configuration

The first thing you should do is to rename the control to reflect it's purpose in your design. You can do this via the right click context menu.

Common Properties

There are a number of common properties that can be configured regardless of the type of display you have selected. First, we have the usual geometric options, allowing you to position and align the control

It is often easier and quicker to resize the control with the mouse (drag the handles) and then right click on the control in the panel and select transform -> restore aspect ratio from the context menu.

We can change the label by using the label property or choose to hide it altogether by setting the showLabels property to false.

Moving Dial Control Configuration

Depending on the theme you've chosen there may be a couple of different moving dial controls such as panel meters or speedometer dials but the configuration options are the same.

Configuration of the number range is a matter of setting the min and max properties and then the number of divisions between them. For example, if we set the range from 0 to 10 with numDivs=5 we would increment by 2 in each division as shown below

The other aspect to the number range is the sub-divisions. Here you can set the number of sub-divisions (numSubDivs) and the length of the indicator for each one (subtickLength). You can also choose not to show the tick indicators at all via the showTicks property

You can adjust both the colour and the font used in the number scale via the tickColour and scaleFont properties

Finally, you can disable animation of the needle by setting animateNeedle to false. This adds a touch of realism to the display when in use by factoring in some basic acceleration and momentum effects.

Seven Segment Display Controls

This type of control includes configuration options for the elements and the for the lamp used to illuminate the segments. You can choose (or change) the number of elements used in the control as well as the spacing between them and the direction of reading.

In terms of colour you can change the colour of the face, the colour of the lamp and also the opacity of the lamp in both it's on and off state. The opacity is a value between 0 and 1 with 1 being fully illuminated and 0 being fully off.

Thermometer Control

The mercury thermometer display controls are trivial and, apart from geometric configuration, have a single property to specify the units as either Celcius or Farenheit.

Loading Bar Control

This reads back a % value based on computational mathematics performed in the program code. A value between 0 and 100 can be represented. In addition to the common properties the following additional properties are available:

init - the starting value of the loading/progress bar

barColour - sets the colour of the indicator bar as it progresses

animateBar - decides whether to animate the bar progress or not

LED Bar (including WiFi, signal, battery indicators)

The following properties are unique to the LED bar type of display.

units - decides whether bar lights up as percentage return or as a set number of steps. If using a percentage return, the % value of each LED is worked out from the total number on the strip. The LED will only turn on when the value reaches mid point between two LED percentages. The only exception to this is the first LED which will always turn on as soon as it has a value assigned.

LEDonColour - Sets the on colour of the LED

LEDoffColour - Sets the off colour of the LED

Gauge

The gauge displays have the following additional properties:

tickDis - Sets the distance of the value ticks from the centre of the gauge

labelDis - Sets the distance of the step values from the indicator ticks

emptyColour - Sets the colour of the gauge when it is empty.

gaugeColour - Sets the colour as the gauge fills.

Programming Methods

The programming methods allow us to access and control the peripheral at run time. The following methods are available in Visual Designer:

Segmented Display

clear - clears all display segments

setValue - allows you to set a numerical value to be printed to the display

setError - allows you to display 'E' error warning on all segments

print - allows you to set a numerical, boolean or string argument to display on segments

setBase - allows you to configure display for Decimal, Binary, Octal or Hex values

setPlaces - allows you to define the number of decimal places the display allows

Thermometer:

setTemperature - allows you to specify the temperature in a numeric value

Dial Controls:

setLabel - Allows you to set a name for the display. This will override any label name you specify in the design properties when program is running

setValue - Same as segmented display

Loading Bar, LED bar, Gauge:

setValue - As above


INDICATORS

Introduction

The indicators section includes LED's of various shapes and sizes for use in front panel design. They all share the same property set.

To add an indicator

1) Right click on the Arduino Yun in the project tree and select the Add IoT Control command from the resulting context menu

2) Make sure the category selector shows Indicator and choose your theme from the selector on the right.

3) Either double click on the indicator to add it directly or click to select and then press the 'Add' button to add it to the project.

Design Time Configuration

Configuration of the buttons can be done primarily at design time once the indicator is placed on the panel. We'd suggest you first rename the indicator to suit it's purpose, then double click on the Mains Control panel to show and finally drag and drop the button control onto the panel.

Renaming and placing an indicator

Once placed, select the indicator by left clicking on it and then view the properties in the property pane at the bottom left of your editor.

Indicator properties

The following properties are commonly available:

Geometry Properties (x, y, width, height)

These properties enable positioning and aligment. For example you could set a series of controls to have the same x value to align them vertically, The width and height properties allow for sizing of the control, although you may find it just as easy to use the 'restore aspect ratio' command on the right click context menu for the control after sizing with the mouse.

Other Properties

ledColour - where available this allows you to set a custom colour for the lamp

labelText - Allows you to set a text label to give meaning to the lamp, e.g. "On"

labelPosition - Allows you to determine where the label will show relative to the lamp, or not to show it at all

labelSpacing - sets the distance of the label from the lamp

labelFont - allows you to customise the text style of the label

Programming Methods

The programming methods allow us to access and control the peripheral at run time. For an indicator there is only one method in Visual Designer:

setValue - allows you to set the state of the lamp in boolean terms. True is on and False is off.


DIALS AND SLIDERS

Introduction

The IoT control library contains a library of both rotary and slider controls. This topic discusses the configuration and runtime properties of these controls.

To add a dial/slider

1) Right click on the Arduino Yun in the project tree and select the Add IoT Control command from the resulting context menu

2) Make sure the category selector shows dials/sliders and choose your theme from the selector on the right.

The theme determines the available styles but not their functionality and lets you create a modern looking GUI or a classic retro panel according to your preference.

Design Time Configuration

Configuration of the controls can be done primarily at design time once they have been placed on the panel. We'd suggest you first rename your control to suit it's purpose, then double click on the Mains Control panel to show and finally drag and drop onto the panel.

Renaming and placing a dial

Select by left clicking on it and then view the properties in the property pane at the bottom left of your editor.

Dial Properties

If you want a text label on a dial or slider to give it a name, this must be done by adding a text element to your front panel.

The geometric properties are available regardless of which type of dial or slider you choose:

Geometry Properties (x, y, width, height)

These properties enable positioning and alignment. For example you could set a series of controls to have the same x value to align them vertically, The width and height properties allow for sizing of the control, although you may find it just as easy to use the 'restore aspect ratio' command on the right click context menu for the control after sizing with the mouse.

Dial Controls

init - sets the initial values of the dial

min, max - sets the range of numerical values for the dial

numDivs, numSubDivs - sets the number of intervals along the range of the dial.

tickLength, subTickLength - sets the size of the individual ticks

amin, amax - sets the distance, in degrees, how far round the dial the labels are placed. Top of the dial is at 0 degrees, with the positive being a clockwise direction

showTicks, showLabels - toggle the visibility of the ticks and labels around the edge of the dial

snapToTicks - Snaps the dial to the closest sub tick or full tick to give precise control of the movement. This can be set to on or off, and is On by default.

fadeOut - sets whether the read out of the dial position stays constantly visible or fades out after a short display following a change in dial position

tickColour, valueFont, labelFont - customise the colour, font and size of the labels and ticks on the dial

Slider Controls

Mainly the same as the dial controls with a couple of extra positional options:

orientation - allows to flip between horizontal and vertical. Recommended over a rotate transform as labels and values will rotate and reposition accordingly.

valuePosition, labelPosition - determine where the values and label will be positioned relative to the position/orientation of the slider.

Programming Methods

The programming methods are the primary means by which you can interact with the control in your firmware program. For dials and sliders we have two exposed methods in Visual Designer.

setValue - allows you to set the value for the dial or slider via the program rather than manually

getValue - reads the value of the dial or slider at its current position.


ALERTS

Using Alert Boxes

An alert control is one which can present a message box to the user with information and a request to confirm. Unlike all other control it does not need to be placed on the front panel itself but it does still need to be picked into the project. As always this is done from the add IoT control command on the Project menu or via the right click context menu in the project tree.

Adding an Alert box.

The basic procedure for using an alert control is :

1) Add it to your project as shown above.

2) Drag the method for the type of alert you want into the appropriate place in your code and type your message.

3) Drag out an event, set the trigger to be the alert and then respond to the users mouse click inside the event.

You'll find more information on events in the IoT Builder help file and event triggers are also discussed in some detail in the Clocks and Timers topic.

Using a confirm messagebox to present info to the user and then clearing the chart data when the user confirms.

The code above will present a message box to the user in the remote user interface (phone/tablet/browser) when executed as shown below:

You'll find a good example of this in the temperature logging sample design which you can launch from the Open Sample button on the Proteus homepage.

Design Time Properties and Programming Methods

There are no design time configuration properties for an alert box and the four types of alert boxes are self-explanatory. It's important to be aware that program execution continues while an alert box is up and that your trigger event is only called when a positive user input is detected.


TextBoxes Terminals

TEXT BOXES AND TERMINALS

Introduction

IoT Builder includes support for various text entry controls. The simplest is a single line text box but you can also have a multiline teletype terminal or a text logger. Regardless of your choice you add the control in the usual way, namely:

1) Select Add IoT control from the Project Menu (or the right click context menu on the project tree).

2) Select the text controls category from the resulting context menu.

3) Choose your control and click add to insert into the project.

Text Input Control

Design Time Properties

Geometry: - Standard geometric properties for sizing and positioning.

readOnly: False allows entered text to be fed back in to the program as a string. True prevents text being entered, good for a notification box.

placeHolder - text to display in the box to prompt the user on the desired input.

maxLength - maximum length of the string allowed to be entered.

Programming Methods

setText: allows the text to be entered into the box which the program can either accept or wait for the user to edit.

getText: reads the string value of the text entered in to the box

clear: removes any entered text from the display, returning it to the place holder value

setError: set an error message in red under the textbox - ideal if a value entered does not meet the required format/length etc of the program

Teletype Terminal Control

Design Time Properties

Geometry: Standard geometric properties for sizing and positioning.

textFont: Sets the font family/size/colour etc for the text printed on the display

placeHolder: text to text to display in the box to prompt the user on the desired input.

maxLength: maximum length of the string allowed to be entered.

clsCmd: instruction required to clear the screen of any previous text.

Programming Methods

print: Print the specified value to the screen. Repeated calls will start printing where the last string finished (i.e. on the same line where possible)

println: Print the required value to the screen on a new line

setBase: Set the unit base for printing interger vlaues (Decimal, Binary, Octal,Hex)

setPlaces: Set how many decimal places are allowed when printing our floating point values

setPrompt:Allows you to set a string as a prompt for text entry - this overwrites the place holder.

getCommand: returns the value in the command variable, or an empty string if nothing is set.

cls: Clears the terminal screen

Text Log Control

Design Time Properties

textFont: set the font to be used when writing to the display

warnColour: sets the colour for any warning text written

errorColour: sets the colour for any error text written

backgroundColour: sets the background colour of the display

Programming Methods

setFile: set the file name for the data to be stored to

setBase: set the unit base for printing interger vlaues (Decimal, Binary, Octal, Hex)

setPlaces: set how many decimal places are allowed when printing our floating point values

info: write a normal log message to the screen

warning: Set an warning text to be displayed on the screen

error: Set an error text to be displayed on the screen

clear: Clears the screen


CLOCKS AND TIMERS

Introduction

There are a range of clocks and timer peripherals that can be added to your front panel to allow you to work with time in your application. As always, these can be picked from the 'Add IoT Control' command on the project menu.

Adding clocks or timers in the generic skin.

Understanding Time

Regardless of whether you are working with a clock or a timer It is really important to understand how your appliance and your GUI acquire time.

Getting / Setting Time

There are two methods to set the time.

1) Linux Time server

You call the waitForTimeServer() method from the server methods in your code - normally first thing in the setup() routine. This will cause the AVR to query the Atheros chip (running Linux) and will return the time.

You then use the now() method in the expression editor to assign the current time to the clock or timer. This is shown below.

Note in this method your appliance itself is aware of the time.

2) Browser time

The alternative is to automatically retrieve the time from the browser which will then apply the time to the GUI control. This is done at design time via the property panel.

If you use the browser time your appliance doesn't necessarily know the time. The first method is safer because your hardware is directly driving the GUI.

Time Events

Each time the time is set you get a set event which you can use to perform action in your program. Amongst other things this would allow you to pass the time to your appliance if you use the browser time method of acquiring time (although note your appliance will still have no idea of time until the browser is live or the app is opened !!!)

You can respond to a set event by dragging out the event handler and then adding the trigger as the time set.

You'll notice that the other event trigger that you can set is an alarm trigger. If you set an event with an alarm trigger it will be called every time an alarm goes off.

You can see all of this in action in the sample design for the alarm clock which you'll find by clicking on the open sample button on the Proteus home page and then typiing 'alarm' in the search box. The sample you want is the 'IoT Alarm Clock'

Clock Properties

Design Time Properties

Geometry - Set position and size of control

label - Title to display on clock face

labelFont - Set font colour, style etc

useBrowserTime - true/false - user browser time instead of time server for display See explanation of different methods to acquire time detailed above.

segColour (digital clocks only) - set digit segment colours

showPM (analog clocks only) - true/false - show or hide the PM indicator

Programming Methods

setTimeMode - allows the user to enter a time on the clock face itself. If passed with parameter 0 the user is setting the clock time and if passed with parameter value 1 through 8 the user is setting an alarm time. So, setTimeMode(0) sets the clock time, setTimeMode(1) sets the time for alarm 1, setTimeMode(2) sets the time for alarm 2 and so on. This can be seen in the alarm clock sample design.

The setTimeMode() method is called when the button is pressed to enable the user to type in a time which will either be an alarm or the clock time itself.

cancelMode - cancel the user entry of the time as entered with the setTimeMode method.

setTime - Set the time of the clock to a specified value (typically now() for real time). read in seconds from midnight 1st January 1970.

getTime - reads the current time of the clock

setAlarm - set the time, in hours and minutes, for each of the alarms

enableAlarm - turns alarm functions on or off for each of the clocks alarms

getAlarm - reads the alarm time

Timer Properties

Please refer to the sample design 'Countdown Timer' for a working example. You'll find this via the Open Sample button on the Proteus Home Page.

Design Time Properties

Geometry : The usual geometry properties enable accurate positioning and sizing for the control.

label: Specify the label for the control that indicates it's function.

dir: Specify the direction of counting for the timer. This defaults to down so a ten second period would result in the timer starting at 10 and counting down to 0. Direction set to up would be the opposite and would start at 0 and count up to 10.

mode: Oneshot mode represents a single timer (unless you stop->restart in code) whereas repeat mode gives you a way to receive periodic callbacks to the timer trigger event in your code.

period: The three period controls let you set the number of hours, minutes and seconds for the timer period. You can also do this in code if you need to change or set at run time.

enableAlarm: this provides a way to disable the alarm when the timer condition is met. Can also be set/unset in code to handle programmatically.

segColour: set the colour of the segments in the display.

Programming Methods

start() : This starts the timer count.

stop(): The stops the timer count

restart(): This will restart the timer count.

setPeriod():set the length of time to elapse before the alarm goes off.

enableAlarm():turn the alarm on or off. If enableAlarm is set to FALSE then the alarm will not trigger and you will not receive an alarm trigger event call. By default, the timer alarm is enabled.

getTime():


LINE CHART

Introduction

The line chart is a control which allows you to log and store data. You can select either a numerical or a time based line chart in the usual way:

1) Select Add IoT control from the Project Menu (or the right click context menu on the project tree).

2) Select the chart controls category from the resulting context menu.

3) Choose your control and click add to insert into the project.

If you choose to have the x-axis as time it is essential that you use the waitForTimeServer() server method in your setup routine so that your appliance actually knows the time. This is discussed in more detail in the topic on clocks and timers.

You'll also find a good working example of the line chart in the temperature logger sample design. You can open this from the Open Sample button on the Proteus home page. In particular, note how the x-axis (time) can be adjusted in code and the chart view updates dynamically.

Design Time Properties

titleText: This property simply lets you set the title for the line chart.

FontSizes: This simply lets you change the size of the fonts on the chart control.

showLegend: This will show or hide the colour key. Without this it becomes hard to tell the difference between lines however it will also take up less space.

pointRadius: This simply allows you to change the size of the different points on the chart. Setting this to 0 will remove the points entirely just leaving the line.

lineWidth: This allows you to change the thickness of the line. Setting this to 0 will hide the line and leave only the points on the chart.

backgroundColour: This will allow you to set the background colour for the selected chart.

timeRange: This property will set the x axis allowing you to display time. This is only available on the time-based line chart. The unit will set what the chart will display in and the range will set how much is shown. If absolute is true the histogram will work off the current time, so if you start it a 1:00 it will also begin at 1:00. If Absolute is false, then it will start at time 00:00 and will increment from there.

Column settings: numColumns simply sets the number of columns available. Then you can go to the individual column settings and change their name, which side the axis is displayed on, colour and range on the y axis.

Programming Methods

setXRange: This allows the user to set the x range, this only works on the numeric line chart control however is available on both.

setTimeRange: Using this you can set the x axis to a time. Unit will determine which time unit is used, then range will determine how many of those units are displayed. If absolute is true the histogram will work off the current time, so if you start it a 1:00 it will also begin at 1:00. If Absolute is false, then it will start at time 00:00 and will increment from there.

setYRange: This will allow you to set the y range on either side of the chart. However if the value provided goes over the designated max or below the designated min then the chart will automatically adjust.

showColumn: This will allow you to show or hide lines. You cannot show a line which isn’t set within the properties.

setDataFile: setDataFile allows you to set which file the graph will read and write to. This is set by entering the file name as a string.

setPlaces: This will set the number of decimal places the histogram will work too.

writeData: Write data will allow you to write a data point to the chart, this will not only update the chart but also store that data in a file if you have linked it.

clearData: This will clear all the data from the chart and delete the data file linked to it.


BAR CHART

Introduction

The bar chart is a data collection and storage control allowing you to set multiple pieces of data and then store them inside multiple files. Files can then be loaded in and displayed next to one another allowing for the comparison of the data. The data files cannot be accessed directly and you must use the read and write commands to interact. You can easily control the colour and labels to make the bar chart stand out.

Example of a single series barchart

Design Time Configuration

numCategories

This Property allows you to set the number of categories. A category is a collection of data for one subject. Categories don’t interact unless told to and each Category will contain data from different times.

categorySet

This allows you to set the names of the different categories making it easier to see which is which.

numSeries

This will set the number of Series. A series is a set of data within a Category. It is important to understand that there is difference in behaviour between series0 and all the other series. series0 is held in memory and can be manipulated programmatically via method calls such as setData(). In order to preserve resources all other series are stored in files and can only be manipulated via the writeSeries() and loadSeries() method calls. So, when you have multiple series in your chart your program will become quite a bit more complicated as you will need to switch data into other series to populate the chart.

setSeries

This allows you to set the colour of each series and the labels which correspond.

titleText

Simply a string to be used as a title

titleFont,scaleFontSize,labelFontSize

Simple properties allowing you to change the size of the text.

showLegend

This allows you to show and hide the Series keys.

minY and minX

This allows you to set the limits of each axis. The graph will however auto adjust if the values go over.

Programming Methods

showSeries

This method allows you to show and hide series. This is useful when displaying different amounts of data. You cannot create series here and the number of series must be set in the design time properties before you can reveal them using this method.

setYrange

This simply allows you to control the Y-range from your program

setData

setData() allows you to set any value to series 0 of a user set category. Note that you can only manipulate series0 with this method. With multiple series you would typically:

- manipulate series0

- writeData() to save series0

-loadData() to load series0 into series1 for example.

-resetSeries() and then manipulate series0 again.

Only series0 can be manipulated in memory. This preserves resources on the 8-bit AVR.

incrementData

This allows you to increase the 0 series on any category by a set value.

decrementData

The reverse of incrementData will remove a set value from the 0 series of any category.

resetSeries

This allows you to reset the data on an individual series. It will apply to all categories.

writeSeries

This will write all the 0 series to a file which you set by inputting a string. This will also overwrite a file if you use the same file name twice allowing you to re-use files.

loadSeries

This is the next step of writeSerise and allows you to read data from a file and apply it to a series. Most basic example would be you have read data from series 0 and then wiped it. You can then apply that read data to the next series along series 1.

clearData

clearData will simply clear all the data files and wipe the graphic.


HISTOGRAM

Introduction

The Histogram is a chart control that allows you to display and store data. It may look more like the bar chart but it behaves more like the line chart with the user setting an x value opposed to a category.

To add a histogram control:

1) Select 'Add IoT Control' from the Project Menu.

2) Select the Charts Category.

3) Choose either the numeric or the time based version of the control.

4) Click Add to insert into the project.

Adding a histogram control.

The control can then be dragged and dropped from the project tree into the virtual front panel in the normal way.

Design Time Properties

Title: Simply allows you to set the title for the histogram.

titleFontSize, labelFontSize and scaleFontSize: Simply allows you to change the font sizes for all the ladled areas.

Background and Bar Colour: Allows the user to set the colours of the background and bars.

X and Y range: Allows you to set the min and max ranges on the x and y axis, the min can be a negative or 0. The x range property will also allow you to set the number of bars displayed on the histogram.

timeRange (Time histogram only) :The time range allows you to set the range of time shown by the histogram. You can also set the number of bars displayed by the histogram. If absolute is true the histogram will work off the current time, so if you start it a 1:00 it will also begin at 1:00. If Absolute is false then it will start at time 00:00 and will increment from there.

Programming Methods

setXrange : setXrange allows you to set the range on the x axis allowing you expand or decrease it and set the number of bars.

setTimeRange (To be used on time histogram only) :This allows you to set the range of time displayed on the x axis. This will not only allow you to set the number of bars available but also set the range of time displayed. If absolute is true the histogram will work off the current time, so if you start it a 1:00 it will also begin at 1:00. If Absolute is false then it will start at time 00:00 and will increment from there.

setYrange :This allows you to set the range of the y axis. However, if the data is larger than the y axis the histogram will automatically adjust and set to the correct range.

showColumn: This allows you to show or hide individual bars on the histogram and therefore filtering your data.

setDataFile:setDataFile allows you to set which file the graph will read and write to. This is set by entering the file name as a string.

setPlaces:This will set the number of decimal places the histogram will work too.

writeData:This will write a line of data to the graph. In addition, if a data file is set it will also write that data to the data file and increment on top of existing data.

When using a time-based histogram use this configuration.

You'll find more information about time methods like now() in the topic on clocks and timers

clearData: This will clear all data from the histogram and corresponding data file.


WindRose

WIND ROSE CONTROL

Introduction

The wind rose is a specialised chart control which has been designed to show data about wind speed and direction.

Please refer to the weather station sample design for a working example on how to use and configure the wind rose

Design Time Configuration

Calm and Petal/Band Properties

The wind rose uses petals to show the direction and wind speed. Because calm wind has no direction it is shown as a circle in the centre. Each wind speed is given a different colour with the top speed at the far end of the petal and the low wind speed at the centre. You as the user can customise the colour of each petal by editing its “band” and the corresponding key will also change. You can also change the label of each band key allowing you to change it from storm to 20m/s if that’s how your software stores the data.

Due the fact not all black text can be seen on a colour you have the option to change the text colour on each key individually. This property is also in the band property group.

Time Properties

The time range property controls how much data is shown by the chart. In this example it will show 24 hours’ worth of data. The unit has 4-options minute, hour, day or month which are the unit. Then simply put the number of units you would like to show.

Colour and Font Properties

These properties are simple aesthetics controlling the font and colour of the text and the colour of the background.

Filename Property

File name will simply create a storage file with that name for your data. You cannot see or access that file directly but by changing it you can be running multiple different files for different wind roses.

Bands Property

Here you can set which band a certain speed will enter. The example here 0-4 mph will be calm, 5-13mph will be band one and so on. This property will always need 5 numbers and cannot operate with any more or less.

Programming Methods

Often the best way to see how something works is to look at an example. The weather station example (accessed via open sample button on home page) makes use of the wind rose and is well worth reviewing before starting your own project.

SetTimeRange - The set time range allows you to set the

StoreReading - Store reading will store the direction and band into a temporary array. The data will not enter the main data file until storeRecord is used.

StoreRecord - storeRecord will transfer all data from the temporary array into the main data file and give it a time stamp.

clearData - clearData will clear the entire data file leaving no data to display.

reload - Reload simply updates the graphic.