We’ve talked a bit about the XNet Database in previous sections of this blog series. But in this part I want to go over some more details about the XNet API. Part 5 of the CAN blog mentioned the Signal API in XNet. In it I showed how Frames can have multiple Signals under it, and each Signal has various attributes like the number of bits, the scaling, and how to interpret the bits of a Frame. But what I didn’t do is talk about the details on how to make a Database, how to import one you may have already, or how to access it programmatically.
XNet Database Editor Basics
The XNet Database Editor is a software utility that is
installed with the XNet driver. It
should be in the Start Menu after installing the XNet software. This utility is a very useful program which
allows users to view and edit XNet Databases.
These Databases can then be used in LabVIEW and referenced by an alias. This makes deployment of system easier in
some ways because settings for the CAN Frames and Signals on a CAN bus don’t
need to be hard coded in the software.
Information like scaling and bit packing can be stored in a single file
and then imported at runtime. Or updated
after the software has been built. There
is a newer version of the XNet Database editor, which NI has called the NI-XNET
Database Editor Preview. As of writing
this blog post it is still a beta, and should eventually replace all the
functionality of the existing editor.
But for now we will be talking about the classic editor.
 |
| XNet Database Editor (Classic) |
 |
| XNet Database Editor Preview |
When making an installer with the Application Builder, the XNet
Database Editor is only included if you add the NI-XNET Utilities as part of
the Additional Installers. To see this
option the Only display runtime
installers checkbox must be off.
If your project has a .DBC file already developed, then you can simply go to File >> Open >> Browse, and select the file. This will then import the file, and assign it an XNet alias name. This is the name to reference this file. This relationship can be changed by going to File >> Manage Aliases
This screen is also useful if you need to deploy Databases
to remote RT systems. Here you can enter
the IP address, user name, and password, then connect. Once connected the RT controller displays the
list of aliases already deployed. You
can then deploy others, or undeploy them.
The Add Alias function on the LabVIEW palette will also add a DBC to the
XNet Database, and similarly there Vis to deploy, undeploy, and list aliases.
But let’s say you don’t have a DBC file, how do you get started? Start by right clicking the Networks, and select Create Cluster and choose the CAN network type. You can make multiple Clusters, for the same or different protocols within the same database. Most configurations only have one Cluster in the database, and the DBC only contains one. For the CAN Cluster you can specify if it is a CAN-FD bus, and the specific Baud Rates used.
While multiple Clusters under a single Database isn’t common, I have used that feature on projects in the past. With it you can have your CAN, and LIN configurations in different Clusters so a single XNet Database contains all you need. There are also times when you may have different CAN buses running at different rates, but they can all be within one Database under different Clusters. But since most buses are separated by different DBC files that also is an easy way to specify which one instead of having a new unique Cluster name.
Under the newly created Cluster you can right click and
select Create Frame. Here you specify a
single Frame of data, which can be sent or received. A Frame is defined in more detail in Part 2
of the CAN blog.
Here you can specify the details about this CAN Frame. Settings like the Frame’s ID, if the ID is
Extended, Payload Length, and other transmission details. The transmission details are most useful for
when the Frame is configured to be sent periodically, but when reading Frames
these settings aren’t important.
Next under the Frame create a Signal. As mentioned earlier Part 5 talks more about what a Signal is and the details around it. Once the Signal is created, you can specify all the various settings for that signal, which is under the Frame, under the Cluster, in the Database.
Most signals are going to be set to the Static Signal
Type. However the Multiplexed, and
Multiplexer signal types are also supported.
Using this a single Frame and its ID can be reused to put more Signals
under that Frame. The Hooovahh CAN Frame
Signal Conversion has two examples in it, and one of them demonstrates the Mux
signal conversion capabilities.
Once all of the Frames, and Signals have been entered, the Database can be saved using File >> Save As. This will save the Database in an XNet format which can be added or updated easily. Another option is the Database can be exported back to a DBC file. This is useful since many non-NI tools can use DBC files. Right click the Cluster and select Export to DBC. This can then be imported like any other DBC file.
XNet Database Editor Limitations
The XNet Database Editor seems to have been developed with a
very generic design in mind. NI
developed XNet wanting it to be used for multiple communication protocols. This is why CAN, LIN, and FlexRay all fall
under the XNet API. As a result there
are some features that I think the XNet Database Editor lacks, which it should
have when compared to other CAN DBC editors.
Enumeration and Attributes are two features available in DBCs, but not
in the XNet Database Editor. However,
these things can be read from DBCs.
The first feature that isn’t available in the XNet Database Editor, but is in a DBC, is the concept of Enumeration when it comes to Signals. Signals in a DBC can have their values mapped to a string representation. There could be a Status signal, and when its value is 0 it means Pass, 1 means Fail, and 2 mean Unknown. Reading these values as numerics is always supported. But the ability to read the value as a string needs extra work, and is only supported when the Database is a DBC. There is no way to set this enumeration relationship from an XNet Database. It is only available if the DBC is used. Reading the Signal enumeration and values can still be done using the Get DBC Attribute VI. Set the Mode to Signal Value Table, and wire in the Signal to be read. Wire an empty string to the Attribute Name, this isn’t used in this mode. What will be returned is a comma delimited string of the Value and String.
A similar feature only found in DBCs is reading the Attributes of Signals or Frames. This also uses the Get DBC Attribute VI. Wiring the Mode to Attribute, then provide the Attribute Name to be read.
XNet Editing Database API
We’ve talked about importing DBCs, and creating the XNet Databases
from scratch using the XNet Database Editor.
But in addition to this, there is an API for creating Cluster, Frames,
and Signals through LabVIEW. From
LabVIEW go to Help >> Find Examples.
Here search for Xnet Database, or the CAN Dynamic Database
Creation. This VI will create a Database
in memory, then create a Cluster and configure it, create a Frame and configure
it, then create a Signal and configure it.
After that it will create a session to read or write the Signal or Frame
as well but that part isn’t necessary for this discussion. Most of the functions needed for these
operations are found under the Measurement I/O >> XNet >> Database
on the functions palette. There is also
a Save VI that can save your created Database and settings. If they aren’t saved the settings are lost
after the session is closed. This Database
can also be Exported to a DBC using a VI on the palette too.
Using these functions you can programmatically import a file, edit it, and resave it. This can become a very useful API if there is a DBC file that needs to be adjusted in some way like renaming, or updating IDs.
Also note that the in memory database is named “:memory:” for a normal CAN 2.0` session, but named “:can_fd:” or “:can_fd_brs:” for the FD and FD BRS protocol types. Here is an NI article on the subject.
If
you have the Hooovahh XNet Tools package installed you can use the Add Alias
from DBC function. This allows you to
select a DBC, and get the alias associated with it. If the DBC hasn’t been added it will add it
first. It can also automate the deploy
process, to remote systems if needed.
Database Access API
If you want to now access the reading of various data from
within a Database, you can use the same functions from the previously mentioned
palette. I have posted the Hooovahh CAN
Frame Signal Conversion package for performing Frame and Signal conversion from
a Database or DBC. The source code is
fully open and available for viewing. In
it you will see how a DBC is first imported, and then the scaling information
is read for all the Signals needed. This
gives information like which bits in which Frames are needed for the
conversion. This information is then
stored so that when a conversion is needed, the low level math can perform the
scale. There isn’t a good NI example for
reading this information but it is fairly straight forward once you understand
the structure of the Database which we already went over.
Drop down a Database Node on the block diagram, then wire a constant to it. Select the Database name from the constant in a drop down menu, it should be populated with aliases on the system. Then read the Clusters from it, select the first one, then pull all Frames from that Cluster. From there you can pull information from each Frame, and each Signal from each Frame. Here is an example.
XNet Read / Write Session Usage
Part 6 of the CAN blog goes into the different ways to read and write XNet data using the XNet API and
XNet hardware. When creating any Signal
Session, the Signals used must be specified, and these come from an existing
Database. When creating any Frame
Session, other than the Stream type, the Frames used must be specified, and
these come from an existing Database.
The Stream sessions, just read or write all Frames immediately, and no
Database, or Frames needs to be specified before creating the session.
String Tricks
All
XNet Database, Cluster, Frame, and Signal datatypes are compatible with the
string datatype. What this means is you
can wire a string in place of any Database input, and as long as it is a valid
alias for a Database, it will use it.
The string equivalent for Clusters, Frames, and Signals gets a bit more
complicated with decimal points, and carriage returns. For the following examples we will use this
demo Database.
The Cluster name is in the string format is this: Demo
Database.ClusterName
The Frame name is in the string format is this: StatusFrame2<Line Feed>Demo Database.ClusterName
The Signal name for the Current Signal is in the format string is this: Current<Line Feed>Demo Database.ClusterName