@sixclear/microstrain-3dm-gx3-euler-angles
MicroStrain 3DM-GX3 Euler Angles v1.0.0
Overview
The MicroStrain 3DM-GX3 Euler Angles plugin communicates with a MicroStrain 3DM-GX3 device over a serial port to collect Euler Angle data: Roll, Pitch, and Yaw. The plugin provides options to store the data to file, publish the data (with optional decimation), display the data (with optional decimation), and more. As with all plugins, the common ‘panel’ and ‘channel’ sections are also available in configuration. The 3DM-GX3 is a high-performance 6-DOF orientation sensor featuring a 32-bit processor, USB and serial host interfaces, and 17-bit resolution on all sensors. It supports data rates up to 1000Hz and provides fully calibrated and temperature-compensated outputs.
User Interface
The MicroStrain 3DM-GX3 Euler Angles interface displays guages for each the roll, pitch, and yaw.
Configuration Example
Configuration Details
ROOT object
This top level object holds all configuration information for a MicroStrain 3DM-GX3 plugin instance.
Required: true
Default: (not specified; see any element defaults within)
options object
Configuration options specific to the MicroStrain 3DM-GX3 plugin.
Required: true
Default: (not specified; see any element defaults within)
options.simulationEnable boolean
Whether to look for and parse expressions in the writeCommand.
Required: true
Default: true
options.simulationSamplePeriod integer
The sample period to use in simulation mode.
Required: true
Default: 100
options.displayEnable boolean
Whether to enable displaying data. Disable this for headless runs to optimize performance (i.e. to prevent queuing for display and display updates).
Required: true
Default: true
options.publishEnable boolean
Whether to enable publishing data. Disable this if there are no subscribers to optimize performance (i.e. to prevent queuing for publishing).
Required: true
Default: true
options.displayDecimationFactor integer
The decimation factor to apply for displayed data. For example, a factor of 5 means to display every 5th sample.
Required: true
Default: 10
options.publishDecimationFactor integer
The decimation factor to apply for published data. For example, a factor of 5 means to publish every 5th sample.
Required: true
Default: 10
options.fileDataQueueTimeout integer
The timeout to use for the file data queueu's dequeue operation in milliseconds. The file handling loop receives data on this queue and we want this loop to be responsive, for example to plugin shutdown, even if the sensor is configured for a very low sampling rate (i.e. elements are added to the queue very slowly). The is essentially the worst-case "hesitation" the user will feel in shutting down this plugin. This value should always be greater than the effective sample period of the sensor, but small enough not to wait too long on shutdown.
Required: true
Default: 1000
options.initializationSequence array
An array defining initial sensor communication to perform.
Required: true
Default:
[
{
"operation": "SendCommand",
"parameters": {
"command": [
"0xD4",
"0xA3",
"0x47",
"0x03"
],
"responseSize": 0
}
},
{
"operation": "FlushBuffer",
"parameters": {
"flushStrategy": "Write Transmit Buffer to Device"
}
},
{
"operation": "Delay",
"parameters": {
"wait": 250
}
},
{
"operation": "SendCommand",
"parameters": {
"command": [
"0xD5",
"0xBA",
"0x89",
"0x03"
],
"responseSize": 0
}
},
{
"operation": "FlushBuffer",
"parameters": {
"flushStrategy": "Write Transmit Buffer to Device"
}
},
{
"operation": "Delay",
"parameters": {
"wait": 250
}
},
{
"operation": "SendCommand",
"parameters": {
"command": [
"0xD6",
"0xC6",
"0x6B",
"0xCC"
],
"responseSize": 0
}
},
{
"operation": "FlushBuffer",
"parameters": {
"flushStrategy": "Write Transmit Buffer to Device"
}
},
{
"operation": "Delay",
"parameters": {
"wait": 250
}
},
{
"operation": "FlushBuffer",
"parameters": {
"flushStrategy": "Flush Receive Buffer (No I/O)"
}
},
{
"operation": "SendCommand",
"parameters": {
"command": [
"0xD4",
"0xA3",
"0x47",
"0x02"
],
"responseSize": 4
}
}
] options.initializationSequence[n] object
An initialization step.
Required: false
Default: (not specified; see any element defaults within)
options.initializationSequence[n]::{oneOf[0]} object
An object defining a command to send to the sensor.
Required: false
Default: (not specified; see any element defaults within)
options.initializationSequence[n]::{oneOf[0]}.operation enum (string)
Sends a command to the sensor.
Required: true
Default: "SendCommand"
Enum Items: "SendCommand"
options.initializationSequence[n]::{oneOf[0]}.parameters object
The parameters for the SendCommand operation.
Required: true
Default: (not specified; see any element defaults within)
options.initializationSequence[n]::{oneOf[0]}.parameters.command array
An array of command byte representations as HEX. For example, to reset the sensor onboard timer back to 0 using the Timer command, we would specify this array as: ["0xD7","0xC1","0x29","0x01","0x00","0x00","0x00","0x00"]. See manual for details.
Required: false
Default:
[]
options.initializationSequence[n]::{oneOf[0]}.parameters.command[n] string
One of the bytes composing this command.
Required: false
Default: "0x00"
options.initializationSequence[n]::{oneOf[0]}.parameters.responseSize integer
The expected response size in bytes for the command. For example, the Timer command returns 7 bytes (commmand byte 0xD7, 4-byte new timestamp value, 2-byte checksum).
Required: false
Default: 0
options.initializationSequence[n]::{oneOf[1]} object
An object defining a step to clear a VISA buffer.
Required: false
Default: (not specified; see any element defaults within)
options.initializationSequence[n]::{oneOf[1]}.operation enum (string)
Flushes the buffer.
Required: true
Default: "FlushBuffer"
Enum Items: "FlushBuffer"
options.initializationSequence[n]::{oneOf[1]}.parameters object
Parameters for the FlushBuffer operation.
Required: true
Default: (not specified; see any element defaults within)
options.initializationSequence[n]::{oneOf[1]}.parameters.flushStrategy enum (string)
Defines which buffer to flush (send or receive) and how to flush the buffer.
Required: true
Default: "Flush Receive Buffer (No I/O)"
Enum Items: "Flush Receive Buffer" | "Write Transmit Buffer to Device" | "Flush Receive Buffer (No I/O)" | "Flush Transmit Buffer"
options.initializationSequence[n]::{oneOf[2]} object
An object defining a step to delay by a specified number of milliseconds.
Required: false
Default: (not specified; see any element defaults within)
options.initializationSequence[n]::{oneOf[2]}.operation enum (string)
Waits the specified number of milliseconds.
Required: true
Default: "Delay"
Enum Items: "Delay"
options.initializationSequence[n]::{oneOf[2]}.parameters object
Parameters for the Delay operation.
Required: true
Default: (not specified; see any element defaults within)
options.initializationSequence[n]::{oneOf[2]}.parameters.wait integer
The number of milliseconds to wait.
Required: true
Default: 500
options.connectionConfiguration object
Defines the Port connection configuration.
Required: true
Default:
{
"Type": "Serial",
"Address": "COM3",
"Timeout": 2000,
"DuplicateSession": false,
"AccessMode": "VISA Defaults",
"BaudRate": 115200,
"DataBits": 8,
"StopBits": 1,
"Parity": "None",
"FlowControl": "None"
} options.connectionConfiguration::{TCP|GPIB|USBTMC} object
An object defining a VISA connection configuration for a TCP, GPIB, or USBTMC device.
Required: false
Default: (not specified; see any element defaults within)
options.connectionConfiguration::{TCP|GPIB|USBTMC}.Type enum (string)
The type of connection.
Required: true
Default: "TCP"
Enum Items: "TCP" | "GPIB" | "USBTMC"
options.connectionConfiguration::{TCP|GPIB|USBTMC}.Address string
The address of the connection / port such as COM1, GPIB1::3::INSTR, TCPIP0::192.168.1.1::54321::SOCKET, USB0::0x2EC7::0x6900::800774011787410049::INSTR, etc. or an array of such addresses. If an array is specified, the plugin uses the first address in the list to successfully open a connection. If none in the array succeed, an error is generated. For TCP connections, note that the number 0 in TCPIP0 is the board number, or interface index, which refers to the local network card. In windows, use the following command in the command prompt / terminal to list the network interfaces and their interface indexes: netsh interface ipv4 show interfaces
Required: true
Default: "TCPIP0::192.168.1.1::54321::SOCKET"
options.connectionConfiguration::{TCP|GPIB|USBTMC}.Timeout integer
The timeout duration in milliseconds used for write and read operations.
Required: true
Default: 2000
options.connectionConfiguration::{TCP|GPIB|USBTMC}.DuplicateSession boolean
Whether to duplicate the session.
Required: true
Default: false
options.connectionConfiguration::{TCP|GPIB|USBTMC}.AccessMode enum (string)
The access mode to use when opening the VISA session: VISA Defaults, Exclusive Lock, Load Configured Settings.
Required: true
Default: "VISA Defaults"
Enum Items: "VISA Defaults" | "Exclusive Lock" | "Load Configured Settings"
options.connectionConfiguration::{Serial} object
An object defining a VISA connection configuration for a TCP, GPIB, or USBTMC device.
Required: false
Default: (not specified; see any element defaults within)
options.connectionConfiguration::{Serial}.Type enum (string)
The type of connection.
Required: true
Default: "Serial"
Enum Items: "Serial"
options.connectionConfiguration::{Serial}.Address string
The address of the serial port.
Required: true
Default: "COM1"
options.connectionConfiguration::{Serial}.Timeout integer
The timeout duration in milliseconds used for write and read operations.
Required: true
Default: 2000
options.connectionConfiguration::{Serial}.DuplicateSession boolean
Whether to duplicate the session.
Required: true
Default: false
options.connectionConfiguration::{Serial}.AccessMode enum (string)
The access mode to use when opening the VISA session: VISA Defaults, Exclusive Lock, Load Configured Settings.
Required: true
Default: "VISA Defaults"
Enum Items: "VISA Defaults" | "Exclusive Lock" | "Load Configured Settings"
options.connectionConfiguration::{Serial}.BaudRate integer
The baud rate to use for serial communication. The available baud rates depend on the serial interface. Common baud rates include: 300, 600, 1200, 2400, 4800, 9600, 38400, 14400, 19200, 57600, 230400, 115200, 460800. Less common though not terrifically uncommon baud rates include: 100, 28800, 56000, 128000, 153600, 256000, 921600.
Required: true
Default: 9600
options.connectionConfiguration::{Serial}.DataBits enum (integer)
The number of data bits used for underlying character encoding for transmission.
Required: true
Default: 8
Enum Items: 5 | 6 | 7 | 8
options.connectionConfiguration::{Serial}.StopBits enum (string)
The number of bits which indicate the end of a given character transmission.
Required: true
Default: "1.0"
Enum Items: "1.0" | "1.5" | "2.0"
options.connectionConfiguration::{Serial}.Parity enum (string)
The parity or error checking convention to use.
Required: true
Default: "None"
Enum Items: "None" | "Odd" | "Even" | "Mark" | "Space"
options.connectionConfiguration::{Serial}.FlowControl string
The flow control convention to use.
Required: true
Default: "None"
options.dataFileConfiguration object
Defines the data file configuration.
Required: true
Default: (not specified; see any element defaults within)
options.dataFileConfiguration.enable boolean
Whether to store sensor data to file.
Required: true
Default: true
options.dataFileConfiguration.filePathTimestampFormat string
The format used for the @VAR{timestamp} variable which may be used with the folderPathFormat and fileNameFormat. This does NOT define the timestamp used in data files. That timestamp is an epoch timestamp (in fractional seconds) anchored at 12am, Jan 1, 1904. Notably, the Timer column in the data file is the sensor timer count value for the sample.
Required: true
Default: "%Y-%m-%d %H-%M-%S%3u"
options.dataFileConfiguration.folderPathFormat string
The folder in which to write data files. Variables @VAR{timestamp} and @VAR{count} are available here.
Required: true
Default: "[Desktop]\\JADE_LOGS\\@VAR{instanceName}"
options.dataFileConfiguration.fileNameFormat string
The filename to use when creating data files. Variables @VAR{timestamp} and @VAR{count} are available here. Note: if the samplesPerFile limit is reached new files will be created accordingly.
Required: true
Default: "@VAR{instanceName}-@VAR{timestamp}-@VAR{count}.csv"
options.dataFileConfiguration.csvHeader string
The following values are written to file: Timestamp, Timer, Roll, Pitch, Yaw. This header should have 5 comma-delimited values (without spaces around the commas) to match the 1 timestamp (local machine timestamp) and 4 sensor data values (Timer, Roll, Pitch, and Yaw) written to file. You do NOT need to include a line feed or carriage return character here, that's taken care of by the plugin as data is written. This configuration option is provided in case you wish to change the csv header names.
Required: true
Default: "Timestamp,Timer,Roll,Pitch,Yaw"
options.dataFileConfiguration.samplesPerFile integer
The maximum number of samples to write to a given file. When this limit is exceeded, a new file will be created according to the fileNameFormat.
Required: true
Default: 100
options.dataFileConfiguration.timestampOffset number
The value -2082844800 seconds helps convert from LabVIEW 'epoch' to POSIX / Unix epoch. The LabVIEW 'epoch' time anchors on midnight Jan 1 1904 whereas POSIX / Unix 'epoch' time anchors on midnight, Jan 1, 1970. Unix Time = LabVIEW Time - 2082844800. The offset is computed as 1907 - 1904 = 66 years which is 24090 days. Add 17 leap year days to get 24107 days, which is 2082844800 seconds.
Required: true
Default: -2082844800
options.logger object
Defines the standard logger for this plugin. Note that a LOG variable space is provided here, as well as the VAR variable space. Available variables are: @LOG{LOGGERNAME}, @LOG{TIMESTAMP}, @LOG{LOGMESSAGE}, @LOG{ERRORMESSAGE}, @VAR{instanceName}, @VAR{timestamp}, and @VAR{acquisition} which contains the entire acquisition object meaning you can index out individual properties such as @VAR{acquisition.sampling.readSamplesPerChannel} are available variables. Note: @LOG{LOGGERNAME} is equal to the @VAR{instanceName} here.
Required: true
Default: (not specified; see any element defaults within)
options.logger.Enable boolean
Whether to enable the logger.
Required: true
Default: true
options.logger.LogFolder string
The folder in which to write log files.
Required: true
Default: "[Desktop]\\JADE_LOGS\\@VAR{instanceName}"
options.logger.FileNameFormat string
The filename to use when creating log files. Note: if the filesize limit is reached new files will be created with enumerated suffixes such as: MyLogFile-1.txt, MyLogFile-2.txt, etc.
Required: true
Default: "@VAR{instanceName}-@LOG{TIMESTAMP}.log"
options.logger.ErrorsOnly boolean
Whether to log only errors.
Required: true
Default: true
options.logger.DiskThrashPeriod integer
The period in milliseconds with which to flush the file buffer to ensure it's committed to the hard drive. Note: This is a performance consideration to prevent writing to disk too frequently.
Required: true
Default: 1000
options.logger.FileSizeLimit integer
The file size at which to create new files.
Required: true
Default: 1000000
options.logger.StartLogFormat string
The initial string to put into the log file when opened for the first time.
Required: true
Default: "**** START LOGGER - @LOG{LOGGERNAME} (@LOG{TIMESTAMP}) ****"
options.logger.EndLogFormat string
The final string to put in the log file when closed.
Required: true
Default: "\n\n**** END LOGGER - @LOG{LOGGERNAME} (@LOG{TIMESTAMP}) ****"
options.logger.LogEntryFormat string
The format to use when writing log entries when errors are not present.
Required: true
Default: "\n\n@LOG{LOGMESSAGE}"
options.logger.ErrorLogEntryFormat string
The message format used to construct error log entries.
Required: true
Default: "\n\n@LOG{ERRORMESSAGE}"
options.logger.TimestampFormat string
The format used by the @LOG{TIMESTAMP} variable.
Required: true
Default: "%Y-%m-%d %H-%M-%S%3u"
panel object
Required: false
Default: (not specified; see any element defaults within)
panel.open boolean
Whether to open the front panel immediately when run.
Required: true
Default: true
panel.state enum (string)
The state in which the window will open.
Required: true
Default: "Standard"
Enum Items: "Standard" | "Hidden" | "Closed" | "Minimized" | "Maximized"
panel.transparency integer
The transparency of the window. 0 = opaque, 100 = invisible.
Required: true
Default: 0
panel.title string
The title of the plugin window when it runs. Note that the variable 'instanceName' is provided here in a VAR variable container.
Required: true
Default: "@VAR{instanceName}"
panel.titleBarVisible boolean
Whether the window title bar is visible.
Required: true
Default: true
panel.showMenuBar boolean
Whether the menu bar is visible.
Required: true
Default: false
panel.showToolBar boolean
Whether the toolbar is visible.
Required: true
Default: false
panel.makeActive boolean
Whether the window becomes active when opened.
Required: true
Default: false
panel.bringToFront boolean
Whether the window is brought to the front / top of other windows when opened.
Required: true
Default: false
panel.minimizable boolean
Whether the window is minimizable.
Required: true
Default: true
panel.resizable boolean
Whether the window is resizable.
Required: true
Default: true
panel.closeable boolean
Whether the window is closeable.
Required: true
Default: true
panel.closeWhenDone boolean
Whether to close the window when complete.
Required: true
Default: true
panel.center boolean
Whether to center the window when opened. Note: this property overrides the 'position' property.
Required: true
Default: false
panel.position object
The position of the window when opened the first time.
Required: true
Default: (not specified; see any element defaults within)
panel.position.top integer
The vertical position of the window in pixels from the top edge of the viewport. Note: this property is overriden by the 'center' property.
Required: true
Default: 100
panel.position.left integer
The horizontal position of the window in pixels from the left edge of the viewport. Note: this property is overriden by the 'center' property.
Required: true
Default: 100
panel.size object
The size of the window when opened the first time.
Required: false
Default: (not specified; see any element defaults within)
panel.size.width integer
The width of the window in pixels. -1 means use the default width for the panel. Note that depending on panel features exposed, there may be a limit to how small a panel can become.
Required: true
Default: -1
panel.size.height integer
The height of the window in pixels. -1 means use the default height for the panel. Note that depending on panel features exposed, there may be a limit to how small a panel can become.
Required: true
Default: -1
channel object
The communication channel definition used by this plugin. Note: this section rarely needs modifications. In many cases, the underlying plugin implementation depends on at least some of these settings having the values below. Consult with a JADE expert before making changes to this section if you are unfamiliar with the implications of changes to this section.
Required: false
Default: (not specified; see any element defaults within)
channel.SendBreakTimeout integer
The timeout duration in milliseconds to wait for sending messages.
Required: true
Default: 1000
channel.WaitOnBreakTimeout integer
The timeout duration in milliseconds to wait for receiving messages. Note: -1 means wait indefinitely or until shutdown is signalled.
Required: true
Default: -1
channel.WaitOnShutdownTimeout integer
The timeout duration in milliseconds to wait for shutdown acknowledgment.
Required: true
Default: 2000
channel.ThrowTimeoutErrors boolean
Whether to throw timeout errors vs simply returning a boolean indicating whether a timeout occurred.
Required: true
Default: false
channel.ThrowShutdownUnacknowledgedErrors boolean
Whether to throw 'shutdown unacknowledged' errors.
Required: true
Default: true
channel.QueueSize integer
The size of the underlying communication queue in bytes. Note: -1 means unbounded (i.e. grow as needed with available memory).
Required: true
Default: 100
channel.SendBreakEnqueueType enum (string)
The enqueue strategy employed on the underlying queue for standard messages.
Required: true
Default: "LossyEnqueue"
Enum Items: "Enqueue" | "EnqueueAtFront" | "LossyEnqueue" | "LossyEnqueueAtFront"
channel.SendErrorEnqueueType enum (string)
The enqueue strategy employed on the underlying queue for error messages.
Required: true
Default: "LossyEnqueue"
Enum Items: "Enqueue" | "EnqueueAtFront" | "LossyEnqueue" | "LossyEnqueueAtFront"
channel.SendShutdownEnqueueType enum (string)
The enqueue strategy employed on the underlying queue for the shutdown message.
Required: true
Default: "LossyEnqueueAtFront"
Enum Items: "Enqueue" | "EnqueueAtFront" | "LossyEnqueue" | "LossyEnqueueAtFront"
channel.FlushQueueBeforeWaitingOnBreak boolean
Whether to flush the queue upon waiting for new messages (i.e. whether to clear the queue and wait for the next 'new' message; this has the effect of removing old messages and waiting for the next message.
Required: true
Default: false
channel.FlushQueueAfterBreaking boolean
Whether to flush the queue after receiving a new message (i.e. whether to handle the next message coming in the queue and then flush; this has the effect of handling the oldest message (if it exsits) or the next message before flushing the queue.
Required: true
Default: false