Dashboard Configuration Tutorial

The dashboard can be configured in many ways, and the number of possibilities might seem intimidating. This page walks through several layouts, starting with simple ones, then bringing in more features.

Just RPM

We'll start with a very simple dashboard with just a single TEXT widget displaying RPM, and updating 16 times per second.

This is our first, so there's some preliminary stuff to go through.

config file sections

The configuration file is arranged in INI file style named sections. Sections, if present, should be in the following order. The red sections always have to be there. Omitted sections will have been set to reasonable defaults.

  1. [GLOBAL} settings for things like Fahrenheit/Celsius, that apply to all pages.
  2. [COLOUR] customise colours.
  3. [RLE] image data for icons and/or logos.
  4. [DLIST] user defined graphics for decoration or alerts.
  5. [PAGE] what to poll and where to display it in one or more screen layouts.

The GLOBAL section has a number of options, but must include the signature from your Megasquirt's firmware. The exact value is important because it tells the dashboard how to interpret values coming from the Megasquirt. To get the value:

  1. Open the folder containing your latest TunerStudio project.
  2. Inside that folder will be the projectCfg folder. Open it.
  3. Open the file mainController.ini.
  4. Look for a line that looks like:
    signature    = "MS2Extra comms342hU" ; Microsquirt
    It should be around 30 to 40 lines down from the top of the file. Carefully note the characters inside the double quotes.
That example string is for a Microsquirt running 3.4.4 firmware, and that will be used for the examples here.

The PAGE section describes the dashboard screens being defined.

create the config file

Back to the dashboard just showing RPM. Here is a first stab:

[GLOBAL]
;
; Megasquirt signature, from INI file
SIG "MS2Extra comms342hU"
;
[PAGE]
main {
        ;
        ; What to ask for
        ;
        poll {
                rpm {method=last}
        }
	;
	; How to display it
	;
        show {
                4 TEXT {
                        var=rpm label="RPM"
                }
        }
}

As mentioned, the GLOBAL section nails down the signature.

The PAGE section here contains one page definition. The word before the first brace is just a name which will appear in the previewer. There is nothing special about the name main.

Inside the definition, the poll block defines what values to collect from the Megasquirt. Each entry has the following structure:

channel_name { options }

channel_name is a name from the [OutputChannels] section of the Megasquirt INI file. Here, rpm was pretty obvious, but you can list all available channels for the signature you entered by clicking on the Channels button in the preview screen.

The options, including the braces, really are optional! The simplest poll block is just a list of channel names. In this case, we are using the last method instead of the default mean. This means rpm will update 16 times per second rather than take the average over 2 seconds.

The show block describes what widgets to show. Its entries have a similar structure:

slot widget-type { options }

The slot is a number from 0 to 15 saying where the widget goes. Slot numbers increase as you go down the screen, with even slots on the left, odd on the right.

The widget-type is one of the standard widgets.

The options depend on which widget you choose and, unlike for the poll block, they aren't very optional. Only the BLANK widget can be used with no options. Here, we use a TEXT widget in slot 4 and tell it to show rpm (from the poll section) and to label the slot with the text RPM (there's only room for 3 characters in the label, so "Revs" wouldn't have worked out).

Incidentally, the layout is pretty flexible and you don't have to do all those indents for braces. It's a programmer's habit, and does help avoid losing track of what matches what.

If you cut and paste this config into the configuration page and click submit you'll get:

main

It's a little boring with a zero. If you edit the show block, and add egval=3500 (example value) to the options, and submit it again you'll get:

main

It feels lopsided sitting over on the left. We could try moving it to slot 5, but that would just be lopsided the other way. There is a way to centre it. Here's the updated part:

	show
        {
		4 BLANK {float=50}
		5 TEXT {
			var=rpm label="RPM" egval=3500
		}
	}

A BLANK widget in slot 4 with the float=50 option tells the widget in slot 5 to "float" leftwards 50% of the width of slot 4.

Here's the result:

Since it's a colour display, we can introduce some colour. One of the default display lists is called bluebg which, not surprisingly, draws a blue background. Here's the part to change:

[PAGE]
main {
	dlist bluebg none none
	;
	; What to ask for 
	...

The first entry of the dlist option happens before anything else is drawn on the screen. Second entry comes after all the widgets have been drawn, but before polling begins. The third comes after the next-page button is pressed, which gives a chance for the current screen to prepare for the next.

If you add that line to the config and resubmit you'll get:

Looks better.

As a last tweak, let's choose one of the other three colours, and use inverse video.

	5 TEXT {
		var=rpm label="RPM" egval=3500
		inv=1 bg=3
	}
That extra line changes it to this:

Maybe better this time, maybe not. The inv option swaps the text and background colours. and bg can be a number between 1 and 4 selecting the background colour (now really the text colour).

Beyond TEXT

The TEXT widget is compact, and with the ability to display 16 of them on the screen, you can pack in a lot of information. However it isn't able to warn you when the numbers start looking bad. Other widgets help with this, but most of them occupy more than one slot. We can easily modify the file to use a SEG7:
	5 SEG7 {
		var=rpm label="RPM" egval=3500
		inv=1 bg=3
	}

Yes, just change TEXT to SEG7; that's it. Here it is:

Same colour scheme, but bigger. Not so nice that the label overlaps with the digit display. We'll leave it off and do something about it later. Now we can make it smarter.

	5 SEG7 {
		var=rpm egval=3500
		inv=1
		cmap=gor low=5300 high=6000
	}

Label's gone. So has the bg option because the thresholds now decide the colour. The gor colour map is one of the default ones which goes green-orange-red. Handy for RPM. The preview gives us:

Green digits. Changing egval shows what happens when the low and high thresholds are crossed.

More Graphical

That's more useful, but it still leaves you reading digits. It is easy to add a LEDBAR to show RPM as a bar gragh. We'll leave the SEG7 in place and put the graph below it.

	5 SEG7 {
		var=rpm egval=4500
		inv=1
		cmap=gor low=5300 high=6000
	}
	10 LEDBAR {
		var=rpm egval=4500
		low=1500 high=6000
		cmap=gor n1=5 n2=3 n3=2
	}

The LEDBAR always has ten segments. The first segment lights when the value passes low. The tenth lights when the value passes high. In this case that means 9 extra segments come on over a 4,500 rpm increase, so each segment is a 500 rpm step. Of course you can choose different values to suit your needs.

We're using the same green-orange-red colour map; n1 says that the first 5 segments will be green, n2 gives us 3 orange LEDs, and n3, 2 red LEDs. It is possible to have a fourth range (n4, of course), but no need since these three ranges have used up all ten LEDs, The gor colour map only has three ranges anyway.

Here's the result:

The orange has already come on for the LEDBAR, but not yet for the SEG7. Doesn't seem much of a problem, but values could be tweaked in either one to get them to agree.

That should have given you a taste of how you use widgets. They all work in similar ways but have their own options. You might like to browse the Widgets reference and try graphing RPM with a CARDIO.

Polling Other Values

We have been polling RPM with the last method, which will update the screen 16 times per second. This suits dynamic things like RPM, MAP, TPS, but things like coolant temperature and battery voltage don't need to follow every jitter. Here is how we can add a coolant temperature TRILED:

	poll
	{
		rpm {method=last}
		coolant {name=clt}
	}
	...
	14 TRILED {
		var=clt egval=183.2 label=CLT
		cmap=bgo low=160 high=200
	}

coolant has been added to the poll list. The default method is mean, so this value will average 32 samples over two seconds and then update the display. The name option sets a different name for the show section to use when referring to this entry. In this case it saves a little typing. It's most useful when you're sampling the one channel twice (say with min and max methods) and need to know which is which.

The TRILED has much the same settings as the SEG7. The label is applied to the text component, and the cmap, low and high apply to the three LEDs.

Here is this setup including the TRILED with three different egval values.

The TRILED is made for values where the middle is the "happy" place since colour and position give you an instant health summary. It means it's great for temperature or voltage, but not so well suited to RPM or oil pressure.

There are some possible improvements to the clt polling.

  1. Round off at the decimal point.
  2. Use min instead of mean
  3. Use degrees Celsius

The first is cosmetic, and the third is an improvement only for people who prefer Celsius. The second is because, when temperature sensors fail, they tend to read erratically, and low, causing warmup enrichment to kick in occasionally. By displaying the lowest value sampled over every two seconds, you're more likely to notice it on the dashboard.

Here is how to make these changes:

[GLOBAL]
degrees C
;
; Megasquirt INI file
	...
	{
		rpm {method=last}
		coolant {name=clt method=min round=1}
	}
	...
	14 TRILED {
		var=clt egval=86 label=CLT
		cmap=bgo low=60 high=92
	}

The temperature units are a [GLOBAL] setting on the basis that if you want Fahrenheit for one temperature, you'll want it for all.

I'm afraid it was a poor design decision to tie egval to the show rather than the poll. It means that the value is simply displayed in the preview without roundoff. May get fixed someday. The value associated with round has to be a power of 10. The sampled value will be rounded at that digit and any digits after that until the decimal point will be set to zero. With round=1, 86.2 would become 86; 86.6 would become 87.

For RPM, round=100 can help avoid jitter in the low digits: 3528 becomes 3500, 3568 becomes 3600.

Decoration

Laying out widgets on the display is pretty flexible, but you can use display lists to personalise the dashboard beyond what the widgets can do. On this dashboard, the label on the SEG7 widget interfered with the first digit of the RPM. We can use a display list to put a label beside the widget.

SIG "MS2Extra comms342hU"
;
[+DLIST]
prescreen {
	call bluebg
	fg base[1]
	movea 180 115 text "RPM"
}
...
main {
	dlist prescreen none none
	...

A plus sign in front of the section name [+DLIST] means that we are adding to the default DLIST. Remember that, to get a blue background, we added bluebg as the screen's first display list. The first dlist has been replaced with prescreen.

Here's an up-close look at what prescreen is doing:

  1. it starts with call bluebg. This draws the blue background display list as before,
  2. fg base[1] sets the foreground colour to colour 1 from the base colour map: white, by default.
  3. movea 180 115 moves the drawing position to these absolute coordinates (i.e. 180 pixels from the left, 115 pixels down from the top). It is important to distinguish movea (which moves to an absolute position) from move (which moves relative to the current drawing position).
  4. text "RPM"draws the text at the current drawing position in the current foreground and background colours. The background colour was already set by bluebg, so we didn't need to set it again.

Here is the result:

Not all that impressive, but you can get more ambitious. For example we might want to cluster the SEG7 and LEDBAR like this:

Besides moving the LEDBAR to slot 8, an extra colour was needed for the darker blue used in the background, and the SEG7 was moved rightwards by reducing the float value.

SIG "MS2Extra comms342hU"
;
[+COLOUR]
revpane = #026
[+DLIST]
prescreen {
	call bluebg
	bg revpane fg base[1]
	movea 5 70 rrectfillbg 230 130
	movea 30 110 text "Revs"
}
...
        show {
		4 BLANK {float=25}
                5 SEG7 {
                        var=rpm egval=4500
Again, using plus, ([+COLOUR]), this time to add the darker blue to the standard set of colours, and named it revpane. The display list starts with the standard blue background, then fills a rounded rectangle in the new colour, and puts "Revs" to the left of the SEG7.

Loading it onto the Dashboard

Now that it's all looking pretty in the web preview, how to load it onto the dashboard?

At the bottom of the preview screen there are two files to download:

  1. dashconfig.s19 contains the screen definition for the first page. If this is the only thing you changed, no changes to colours or display lists or other pages, this is the only file you need to load.
  2. dashenv.s19 contains the colour table, display lists and any second, third, etc. page definitions. If you only change an existing colour, say, this is the only file you need to load.

If you're not sure, grab both.

To load them onto your dashboard you need:

Flan uses the Megasquirt Serial Protocol which allows the Megasquirt to act as a bridge to the CAN bus and on to the dashboard. It can be used to install new configuration files or to upgrade the dashboard firmware. On the downside, flan is command line only. Maybe pretty pictures on the dashboard, but plain text and keyboard to get it there.

In this case you can load the new config files:

flan -p [serialport] -c 10 dashconfig.s19 dashenv.s19

transfers the config and environment images to the dashboard. The serialport depends on your computer. If you're using a built-in serial port under Windows it will usually be called COM1 or COM2, if you're using a USB adaptor it will be some higher COM number. You can look this up in the Windows Device Manager

Under Linux, a built-in port would be /dev/ttyS0 or /dev/ttyS1; a USB one could be something like /dev/ttyUSB0 or /dev/ttyACM0. An ls /dev/tty* should give you some idea.

The -c 10 refers to the Megasquirt CAN protocol device ID for the dashboard. It defaults to 10, but can be any value 1 to 14. This needs to be the device ID currently configured on the dashboard, regardless of what is in the configuration you're loading.

If all goes well, a few dots will appear on the screen showing progress and it will complete in a couple of seconds. The dashboard will automatically reboot and, with luck, you'll see the same layout as you had in the web preview.

Closing Remarks

This tutorial has sketched the sorts of things you can control when designing a dashboard. Display lists were only covered lightly. There is a separate, geekier tutorial covering support for drawing icons and logos.

If you have followed everything in this tutorial you should be in good shape to understand the configuration reference pages.