This API is under active development, feel free to offer suggesions on how we can make this easier!
We are open to suggestion on how to make this process easier and more entuitive/powerful!
We plan to make this easier to work with in the future, where there is no worry of git removing custom gauges.
You need to create the custom gauge file in the local/guages/custom.py
directory:
from kivy.uix.label import Label
from digitaldash.face import Face
from kivy.logger import Logger
from kivy.uix.relativelayout import RelativeLayout
from digitaldash.base import Base
from kivy.lang import Builder
# KV Styling, here we set color of our text
Builder.load_string("""
<MyCustomLabel>:
color: 1, 0, 0, 1
""")
class MyCustomLabel(Label):
'''Custom label class'''
def setData(self, val) -> None:
Logger.info("Custom gauge setData method called")
class Custom():
def __init__(self, pid=''):
super(Custom, self).__init__()
Logger.info("Instantiate new custom gauge")
def buildComponent(self, **ARGS) -> []:
self.container = ARGS['container']
liveWidgets = []
label = MyCustomLabel(text='Custom gauge!')
# Use Kivy RelativeLayout as our gauge layout
layout = RelativeLayout()
# This bit is needed to add your gauge to the main layout
layout.add_widget(label)
self.container.add_widget(layout)
# We can add out label here if we'd like it to receive data
liveWidgets.append(label)
# Need to provide a pid attribute for our label to update from,
# see static/constants.py
label.pid = '0x0C'
return liveWidgets
Once you create the new custom gauge python class you also need to register it in the local/gauges/__init__.py
file:
from local.gauges.custom import *
or you can give it a fancy name:
from local.gauges.custom import Custom as KECustom
To include the new custom gauge in the guages config you can add the following to your config:
{
"module" : "KECustom",
"path" : "/Custom/",
"themeConfig" : "Custom",
"pid" : "0x010C",
"unit" : "PID_UNITS_RPM"
}
If you do not need a required parameter like pid or unit then you can use the value "n/a" which is treated special.
buildComponent
: This is the method that is called to instantiate the new gauge, it is required!
container
: This is a kivy.uix.relativelayout for any kivy widgets that you'd like to add to the current gauge display.
liveWidgets
: This is an array of Kivy widgets that you want to receive data ( think labels that update etc ) each widget object should have a setData
method to recieve this data!
pid
any object receiving data needs to have a pid
attribute ( ie label.pid = '0x010C'
), this value can be set to None
if the gauge does some kind of updating but does not need data.
return liveWidgets
: The new gauge must return the liveWidgets
array at the end of the buildComponent
method!
Styling is handled by the KV Kivy langauge think of it like CSS but not really.