Compass

Who it’s for

Anyone reading a bearing rather than a magnitude — wind direction on a weather station, vehicle heading, the orientation of a rotating machine or an antenna. The reader wants a direction, and a compass rose says north-east faster than the number 45 does.

What it does

The Compass draws a bearing as a needle on a compass rose. A value of 45 points the needle to NE on a dark plate with cardinal labels, twenty-two minor ticks between them, and a cycling animation that swings the needle to each new bearing rather than snapping it.

• Direction is read as direction — the reader recognizes the pointing rather than converting a number into a heading.
• Cardinal labels are configurable, so the rose can carry the four points, the eight points, or degrees.
• Animation can move the needle or rotate the plate, matching either a fixed-card or a rotating-card instrument.
• Plate, border, needle, needle circle and tick colors are styled independently, so the compass can match a dark or a light dashboard.
• Values are expected in the 0 to 360 range, which is the convention every bearing source already uses.
• Units are converted, not just appended — the widget respects the unit set on the key and converts to the unit chosen on the widget.
• The Compass shows one current bearing: it draws no wind rose, no history and no magnitude, so wind speed belongs on a separate gauge beside it.

How to set up

Data keys

The Compass takes one datasource, one entity and one data key.

Key	Role	Type	Description
Any bearing key	The direction the needle points to	Timeseries	Numeric, expected between 0 and 360, where 0 and 360 are both north. An attribute works equally well.

Confirm the source reports a compass bearing rather than a signed angle. A sensor sending −90 for west has to be normalized upstream, since the rose has no negative side to point at.

How to customize

• To label more points on the rose — edit the Major ticks labels, which ship as the four cardinal points and accept eight points or degree values instead.
• To change the resolution between labels — set the Minor ticks count.
• To rotate the card instead of the needle — set Animation target to Plate, which matches a rotating-card instrument.
• To change how the needle settles — set the Animation duration and easing rule; the shipped cycle rule gives the needle a physical swing.
• To match a light dashboard — set the Plate color, tick colors and label style, which ship configured for a dark plate.
• To restyle the needle — set the Needle color and the Needle circle size and color.
• To drop the outer ring — turn off the Plate border, or adjust its width and color.

Tips

• Put the compass next to a magnitude gauge rather than trying to show both. Wind direction and wind speed are two readings, and a dashboard that pairs a compass with a small speed dial is read faster than any single instrument attempting both.
• Keep the cycle animation rule on any bearing that can cross north. The swing makes a needle passing from 350 to 10 look like a small movement, whereas an instant jump reads as the sensor having failed.