Readonly deviceMaps a device serial number to a device.
new Map([
["8502-03-0001353-2115", { deviceAddress: 2045285448, ... }]
]);
When making requests related to a device, the device address is used as an identifier. The device address is not permanent. The number is regenerated by Motion Master when devices are power-cycled. For scripts and applications using this library, having a permanent device identifier is a better option. The device serial number read from the hardware description file (.hardware_description) stored on a device is a permanent identifier.
This map helps in making all request methods related to a device accept a device reference instead of just a device address as an identifier. The device reference DeviceRefObj can be one of the following: device address, device serial number, or device position. Before sending a request message to Motion Master, the device address is resolved from the device reference, and this map is used for that.
Readonly deviceMaps a device address to a map of parameter ID to a type value key.
new Map([
[2045285448, new Map([
["0x1018:02", {
id: '0x1018:02',
index: 4120,
subindex: 2,
name: 'Product Code',
unit: '',
group: 'Identity object',
readAccess: true,
writeAccess: false,
min: undefined,
max: undefined,
valueType: 7, // UNSIGNED32
typeValueKey: "uintValue"
}]
])]
]);
When setting a parameter value, only one of int, uint, float, string, or raw type value fields must be set. This is defined in the proto file SetDeviceParameterValues request message.
Device parameters have a richer set of base types defined in ESI, and they are provided by the DeviceParameterInfo status message.
When device parameter info is fetched, this map gets updated by mapping device parameter types to "oneof" proto types, e.g., INTEGER32 -> intValue.
This map helps in simplifying the API by allowing users to set parameter values without specifying the type value field.
One can simply call setParameterValue(2045285448, 0x2004, 0x03, 2500), and the correct type value field on the proto message will be set, uintValue in this example.
Readonly socketApply set point.
When running in position profile mode and setting a new position target value, it's important to note that the device won't immediately move to the new position. To execute a new position set-point or target value, you need to make certain changes to the controlword.
To indicate that the new set-point is valid and should be executed, you need to trigger a rising edge of the new set-point bit in the controlword. This rising edge serves as a signal to the device that a new set-point is being provided.
Once the device receives the rising edge of the new set-point bit, it will set the set-point acknowledge bit in the statusword to 1. This indicates that the device has acknowledged the new set-point and will execute the corresponding action, such as moving to the specified position.
Afterwards, the device will signal its ability to accept new set-points by setting the set-point acknowledge bit back to 0 in the statusword. This signifies that the device is ready to receive and process additional set-points.
It's important to note that the device won't wait for the previous set-point to finish before executing a new set-point. If you want to initiate a new set-point while the previous one is still being executed, you need to generate another rising edge of the new set-point bit in the controlword.
Compute auto-tuning gains.
Auto-tuning gains can be computed for the position or the velocity controller.
The prerequisites for running this procedure are a configured motor and the existence of the plant_model.csv file created by previously running the system identification startSystemIdentification. Motion Master will return an error if the plant_model.csv file is not found.
In OBLAC Drives, this request is called when the tuning sliders (damping ratio, bandwidth) are moved and during the CTC recording startCoggingTorqueRecording when auto-config is not skipped.
Motion Master will compute the PID gains using a proprietary algorithm and update the Kp, Ki, Kd values of the 0x2011 and 0x2012 parameters.
Optional messageId: stringuse startFullAutoTuning instead
Optional messageId: stringPrivate createOptional messageId: stringPrivate createOptional valueTypeKey: "intValue" | "uintValue" | "floatValue" | "stringValue" | "rawValue"Optional messageId: stringDelete device file.
Motion Master uses Filetransfer over EtherCAT (FoE) to delete files from the device flash memory.
If the file to delete is written in parts, Motion Master will ensure that all parts are deleted. It does this by reading the list of files on a device, see getDeviceFileList, removing all parts from that list, and then re-reading the list again to ensure that there are no leftovers if there were more than 32 files in the list. If there are still more than 32 files in the list, Motion Master will blindly try to make sure there are no file parts left in the memory (may or may not work).
Optional messageId: stringDelete file.
Optional messageId: stringA helper function to disable motion.
Optional messageId: stringDisable motion controller.
Depending on the current CiA402 state, this request will do the following:
Optional messageId: stringOptional valueTypeKey: "intValue" | "uintValue" | "floatValue" | "stringValue" | "rawValue"Optional requestTimeout: numberOptional messageId: stringOptional valueTypeKey: "intValue" | "uintValue" | "floatValue" | "stringValue" | "rawValue"Optional requestTimeout: numberOptional messageId: stringOptional messageId: stringHelper function to enable motion.
Optional messageId: stringEnable motion controller.
This request will set the mode of operation to CSP, CSV, or CST and optionally enable filtering.
If filtering is enabled, Motion Master will compute an intermediate target value in each cycle, and depending on the active mode of operation, set the value of one of 0x607A Target position, 0x60FF Target velocity, 0x6071 Target torque to that value.
The target value can be updated with setMotionControllerParameters.
Optional messageId: stringProtected fixFixing a production screw-up that affects a very important customer. Added on February 29th, 2024. Besides fixing the production screw-up, this function will return a dummy .hardware_description file if one is not found on the device.
Get CiA402 state.
Optional messageId: stringGet Circulo encoder magnet distance.
This feature is only available for firmwares >=v5. For older firmwares, Motion Master will return an error.
Motion Master will read registers 0x2B and 0x2F on the specified encoder (by encoder ordinal), and then it will compute the magnet distance. The computation depends on the Circulo type, encoder port, and ring revision.
Optional messageId: stringGet cogging torque data.
The cogging_torque.bin file is the result of cogging torque compensation recording, as explained in startCoggingTorqueRecording. The size of this file is 2048 bytes, where each pair of bytes represents a 16-bit signed integer value in mNm (millinewton-meter).
Motion Master will read the cogging_torque.bin file, convert the bytes to 16-bit signed integer values, and return them as an array of numbers.
Optional messageId: stringGet decoded file.
Content of a device file is returned as a binary data buffer. This functions tries to decode the content as a text in utf-8 character encoding.
Optional messageId: stringGet device CiA402 state.
Optional messageId: stringGet device file.
Motion Master uses Filetransfer over EtherCAT (FoE) to read and send back the content of a file from the device flash memory.
The IgH EtherCAT Master library used by Motion Master limits the file read buffer to 9KB, so any file written to flash that is larger than 9KB needs to be split into parts of max 9KB. Motion Master does this automatically on request to setDeviceFile.
Upon receiving this request, Motion Master will first read the list of files on a device, see getDeviceFileList. It does that in order to determine if the requested file, for example, "SOMANET_CiA_402.xml," has been stored in multiple parts. The parts are named like "SOMANET_CiA_402.xml.zip.part000," "SOMANET_CiA_402.xml.zip.part001," and so on. Motion Master will read all parts of the requested file, unzip it, and send the content back to a client. Since the number of items in the list of files is limited to 32 (based on the firmware version), Motion Master might not see the file, but in any case, it will try to read the content of it. If the file exists, it will return its content; otherwise, it will return the file not found error.
Zipped files will be automatically unzipped, and their content returned; for example, "stack_image.svg.zip" can be stored in one or multiple files depending on the size. No matter how it's stored, it will be unzipped, and its content returned as text (SVG) instead of zipped content (binary).
In BOOT EtherCAT state, it's only allowed to read the .hardware_description file. This was done because the bootloader firmware would hang when trying to read a corrupted or missing file.
If the requested file content is empty, Motion Master will return a not found error. This is subject to change now that Motion Master reads the file error codes.
Optional messageId: stringGet device file list.
Motion Master will use Filetransfer over EtherCAT (FoE) to obtain the list of files from a device. There isn't an actual command for getting the list, but rather the content of a specially named file "fs-getlist" is the file list. The list can be read like any other file from a device using the IgH EtherCAT Master for Linux CLI program:
$ ethercat foe_read fs-getlist
At the time of writing this document, "fs-getlist" can return a maximum of 32 files (subject to change) in the list. This is a firmware limitation. However, more than 32 files can be stored on the device flash memory, but they won't appear in the list. Also, note that FoE can behave differently in the bootstrap firmware, which runs in the BOOT EtherCAT state, and SOMANET firmware, which runs in other EtherCAT states like PREOP/OP. Bootstrap tends to be buggier since it cannot be updated easily, so Motion Master has certain workarounds to overcome these FoE differences and bugs.
Optional messageId: stringGet device info.
Device info includes a list of devices on the network. Each device has a type, position in the network, and a device address. At the time of writing, the device alias is not yet supported.
Motion Master will assign a unique device address to each device in the list.
The device address is what the client libraries use to make requests like getDeviceParameter for a particular device.
The device address is only valid for the duration of the session, that is, until Motion Master re-initializes the devices, for example,
when devices are power cycled or the Motion Master process is restarted.
Optional messageId: stringGet device log.
The device log is stored in two files due to the IgH EtherCAT Master library 9KB file size limitation, as explained in getDeviceFile. The device automatically writes the log to logging_curr.log and copies that file to logging_prev.log once it reaches 9KB. When Motion Master receives this request, it will read both of these files and return their combined contents.
Optional messageId: stringGet device parameter info.
Device parameter info includes a list of all parameters for the requested device, but without the parameter values. Getting device parameter values can take more than 20ms per parameter using the IgH EtherCAT Master library. Not all clients require all the parameter values at once, like OBLAC Drives, so this method is useful for getting the list of available parameters and then separately obtaining the values of some required parameters.
The returned list of device parameters will include some basic data for each parameter: index, subindex, name, unit, group (ARRAY or RECORD name for subitems), read and write access, min and max, and value type. Min and max values are not yet fully supported - they contain the min/max values for the used base type. The same info and more can be read from the "SOMANET_CiA_402.xml" file, but getting info from the ESI file is more complicated. It requires an XML parsing library and knowing how to read objects info from a dictionary and assigned modules.
Optional messageId: stringGet device parameter values.
As mentioned earlier, fetching parameter values can take 20ms or more. However, it can also fail completely or timeout on the master side, registering as a "cannot refresh value" error.
Optional messageId: stringGet device parameters.
Get the EtherCAT network state.
Returns one of the EtherCAT network states: BOOT, INIT, PRE-OP, SAFE-OP, OP. The state is returned as an enum value: INIT: 1, PREOP: 2, BOOT: 3, SAFEOP: 4, OP: 5.
Optional messageId: stringGet multi-device parameter values.
Allows requesting parameter values from multiple devices at the same time.
Optional messageId: stringOptional loadFromCache: booleanOptional requestTimeout: numberOptional messageId: stringOptional loadFromCache: booleanOptional requestTimeout: numberOptional messageId: stringOptional messageId: stringGet the device serial number by device address.
This function does not make any requests; instead, it utilizes the previously mapped device serial number to an instance of a device.
Get system log.
The system log represents the collected standard output from the Motion Master process.
This request will return the entire system log, which can be a maximum of approximately 2MB.
The log level can be set as an environmental variable when the Motion Master process is started. The log level can be selected in the OBLAC Drives Update Service expert mode before installing a release. The supported log levels are:
Optional messageId: stringGet system log lines.
Get the system log content and parse it into an array of lines, where each line contains the date, uptime, ID, file, level, and message.
Optional messageId: stringGet the system version.
Retrieve the version of Motion Master. The version follows Semantic Versioning 2.0.0.
Optional messageId: stringMatch parameter value.
This function will retrieve a parameter value from a device and compare it with the expected value.
Will throw an error if the values do not match.
Pings the system.
The client must send messages to Motion Master at regular intervals for Motion Master to consider it alive. When the client is considered "not alive", Motion Master will stop the ongoing procedures and monitorings started by that client. Each client on the Motion Master side has its own default timeout, which can be changed by setSystemClientTimeout.
Optional messageId: stringReset device fault.
When an error occurs on a device, the device will go into the Fault reaction active state (transition 13) and then automatically to the Fault state (transition 14). The CiA402 state of a device can be derived from the value of the Statusword object (0x6041:00). In order to exit the Fault state and enter the Switch on disabled state (transition 15), the master must send a Fault reset command via the Controlword object (0x6040:00).
When this request is sent to Motion Master, it will attempt to reset the fault. Resetting the fault can either succeed or fail. While resetting the fault, Motion Master will use the current Controlword value and set the Reset fault bit to 1. However, upon completion, whether successful or encountering an error, Motion Master will set it back to 0.
Motion Master will return a "No Fault" warning when this request is sent, and the device is not in the Fault or Fault reaction active state. If this request is sent when the device is in the Fault reaction active state, Motion Master will wait for the automatic transition (14) to the Fault state before attempting to reset the fault. When Motion Master sets the Controlword Fault bit to 1, it will also periodically check if the device is no longer in the Fault state. After a few seconds, if the device is still in the Fault state, Motion Master will give up and return a timeout error.
Optional messageId: stringReset fault.
Resetting a fault can only be done from the FAULT CiA402 state by transitioning to SWITCH_ON_DISABLED. This function will do the rising edge, that is it will first set the controlword reset fault bit to 0, wait a bit, and then set it to 1.
Resolve a device.
Resolves the device object by its reference, which can be a position, serial number, or device address.
This function will make requests to retrieve the list of devices and the .hardware_description file for each device, but only if it has not been previously retrieved for this session.
errors if the device reference is invalid
Resolve device address.
This method should return the device address by a device reference object, or throw an error if the device address cannot be found.
Refer to the description of this class for more information.
Optional typeValueKey: "intValue" | "uintValue" | "floatValue" | "stringValue" | "rawValue"Private resolveOptional b: number | booleanOptional c: numberOptional d: string | number | booleanOptional e: numberOptional f: stringPrivate resolveResolve set device parameter value arguments.
Optional c: number | "intValue" | "uintValue" | "floatValue" | "stringValue" | "rawValue"Optional d: ParameterValueTypeOptional e: "intValue" | "uintValue" | "floatValue" | "stringValue" | "rawValue"Optional f: numberOptional g: stringRestore default parameters.
Command the device to restore the default parameters, then delay initially and subsequently check if the value of the Restore default parameters has changed to 1, indicating the successful completion.
https://www.synapticon.com/documentation/circulo/sw5.0/device_info/save_restore_config.html
Run OS command.
The OS command is a standard way of triggering actions or services that cannot be accommodated through a single SDO upload/download.
The Dictionary object 0x1023 is used for executing OS commands. The following is the subindex list and their meanings:
Note that:
All possible cases of 0x1023:03 Response subindex:
| Description | Byte 0 | Byte 1 | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Byte 6 | Byte 7 |
|---|---|---|---|---|---|---|---|---|
| Command in progress with percentage | 100-200 | - | - | - | - | - | - | - |
| Command in progress without percentage | 255 | - | - | - | - | - | - | - |
| Command completed without errors and without response | 0 | - | - | - | - | - | - | - |
| Command completed without errors and with response | 1 | - | Data | Data | Data | Data | Data | Data |
| Command completed with error and without response | 2 | - | - | - | - | - | - | - |
| Command completed with error and with response | 3 | - | OS error code | Data | Data | Data | Data | Data |
Note that in the case of "Command completed without errors and with response," 6 bytes can be used for data. However, only 5 bytes are available in the case of "Command completed with error and with response." This limitation arises because Byte 2 in the latter response is allocated for the OS error code. The OS error code serves to indicate the reason behind the error occurrence.
0x1023: OS command is used in combination with 0x1024: OS command mode object. In our firmware, only the values 0 and 3 from the 0x1024 command mode object (USINT) are handled, and their meanings are as follows:
Note that if you abort the OS command, you must switch the value of 0x1024 back to 0 before executing another OS command.
Send request.
Create a Motion Master message with the provided request, optionally generate a unique message ID, and then send the message through the socket.
the message ID
Optional messageId: stringSet device CiA402 state.
Optional messageId: stringSet device file.
Motion Master uses Filetransfer over EtherCAT (FoE) to write files to the device flash memory.
The IgH EtherCAT Master library used by Motion Master limits the file read buffer to 9KB, so any file written to flash that is larger than 9KB needs to be split into parts of max 9KB. Motion Master does this automatically by first zipping the content and then writing the parts. The parts are named in the following manner: "SOMANET_CiA_402.xml.zip.part000," "SOMANET_CiA_402.xml.zip.part001," and so on.
Optional messageId: stringSet device parameter values.
Optional messageId: stringSet the EtherCAT network state.
Set the EtherCAT network state to one of: BOOT, INIT, PRE-OP, SAFE-OP, OP. The state is set by an enum value: INIT: 1, PREOP: 2, BOOT: 3, SAFEOP: 4, OP: 5.
When switching from PRE-OP to OP, MM will reinitialize slaves to update the PDO mapping.
Optional messageId: stringSet halt bit.
The behavior of the halt function (bit 8) in the controlword depends on the specific operation mode of the device. When the halt bit is set to 1, the commanded motion will be interrupted, and the behavior of the device will follow the defined rules for the halt option code.
After releasing the halt function by setting the halt bit to 0, the drive device will attempt to continue the commanded motion if possible, based on the specific operation mode and the conditions of the system.
A helper function to set the value of the Modes of Operation parameter (0x6060:00).
Set motion controller parameters.
This request sets the target value for a device on Motion Master.
A previous call to enableMotionController will set the mode of operation to CSP, CSV, or CST and optionally enable filtering.
Optional messageId: stringSet multi-device parameter values.
Allows setting parameter values on multiple devices at the same time.
Optional messageId: stringOptional valueTypeKey: "intValue" | "uintValue" | "floatValue" | "stringValue" | "rawValue"Optional requestTimeout: numberOptional messageId: stringOptional valueTypeKey: "intValue" | "uintValue" | "floatValue" | "stringValue" | "rawValue"Optional requestTimeout: numberOptional messageId: stringOptional messageId: stringSet signal generator parameters.
This request will update the signal generator parameter values for a device on Motion Master. The selected signal generator is then started by startSignalGenerator. The signal generator must be started within the next 60 seconds before Motion Master invalidates the previously set parameters.
Optional messageId: stringSet system client timeout.
This request will update the client timeout.
The client timeout specifies how long Motion Master will wait for the client to send a ping or any other message before considering it gone and clearing the resources (stopping procedures and monitorings) related to that client.
The default client timeout is 1000ms.
Clients will typically change this once the socket connection is established.
Optional messageId: stringStart Circulo encoder configuration.
The preconditions for this procedure are to have a Circulo device with internal encoders and firmware >=v5.
This procedure will set various internal encoder registers based on the hardware description, Circulo device type, and the encoder ordinal.
Before updating the registers, Motion Master will send an OS command to ignore the BiSS status bits. Once the procedure is done, the value of this register will be reverted.
Depending on the setup, this procedure can take up to 30 seconds.
This procedure can fail if it's already running, if it's not supported because of the firmware version, or if the hardware description file is missing.
While this procedure runs, Motion Master will report its progress.
Optional messageId: stringStart the Circulo encoder narrow-angle calibration procedure.
This feature is only available on firmwares >=v5.
Before starting the procedure, Motion Master will check and return an error if:
Before starting the procedure, Motion Master will do the following:
The parameter values Motion Master sets depend on the type of the device (fetched from the hardware description file). Once the operation has completed, Motion Master will roll back all of the above parameters to their initial values.
Procedure:
The result of a successful calibration is setting multiple parameters into registers of the specified encoder.
At the end of the procedure Motion Master will rotate the motor back to the starting position and run commutation offset detection. There will also be a final iteration that only measures the values of a (now) calibrated encoder for display.
This request will turn the motor.
Optional messageId: stringStart cogging torque recording.
Cogging torque compensation (CTC) recording can be initiated with or without auto-config. In the proto file, skipping the auto-config is currently named skip_auto_tuning. The field name is deprecated and will be renamed.
If CTC recording is started without auto-config, users must ensure that the encoder on the motor shaft is used for all functions: commutation, position, and velocity. If this is not the case, Motion Master will return an invalid encoder configuration error. Recording can also fail if the position controller is not tuned.
If CTC recording is started with auto-config, Motion Master will:
All parameter values that Motion Master changes as part of the auto-config are first stored in memory and once the CTC recording is done, they are reverted back.
CTC recording is initiated by changing the Modes of operation (0x6060) parameter value to -1 (Cogging compensation recording mode). During the operation, Motion Master will monitor the Cogging torque compensation state parameter (0x2008:01) to know when the recording is in progress and when it's done.
The result of CTC recording is the cogging_torque.bin file written to the device flash memory. The size of this file is 2048 bytes. Each pair of bytes represents a 16-bit signed integer value in mNm (millinewton-meter).
This request will turn the motor.
Optional messageId: stringStart device firmware installation.
When Motion Master receives this request for a device, it will perform the following steps:
During the firmware installation, Motion Master will send progress messages back to clients. If Motion Master encounters a failure in any step other than SII write, it will send an error. If SII write fails, only a warning will be sent.
Optional messageId: stringStart device SII restore.
This request uses the EEPROM tool from SOEM to overwrite the SII portion of the EEPROM on a device.
Motion Master will verify the provided SII file before writing it to EEPROM. It will:
Unlike IgH EtherCAT Master, which identifies interfaces by MAC address, the SOEM tool requires an adapter name. Before calling the SOEM tool, Motion Master will find the adapter name by looking into /sys/class/net.
The SOEM tool binary is delivered as a part of the Motion Master Docker image.
Optional messageId: stringStart full auto-tuning.
The preconditions for running the full auto-tuning are a properly configured motor, brake, and encoders, and having executed the offset detection and the system identification procedures.
In order to successfully run the full auto-tuning procedure, the motor must not rotate, and the device must not be in CiA402 Operation enabled.
Motion Master will try to read the plant_model.csv file, and if it doesn't exist, it will return an error.
Before the operation starts, Motion Master will measure the actual velocity for 500ms at a standstill to determine the encoder noise. The noise is then sent, along with some other parameters (velocity feedback filter, feed forward, DC link voltage, firmware version, and similar) and data to a proprietary computation algorithm. ADC current ratio, which is used in the computation script, is determined by the firmware version and the device hardware ID (e.g., 9500, 9501, 8501...).
Full auto-tuning will compute the PID gains, and Motion Master will update the parameter values in the velocity or position controller, depending on the request.
Motion Master will return the damping ratio, settling time, and bandwidth values when the procedure completes. UI will use these values to update the sliders in the Tuning screen.
This procedure can be stopped with stopFullAutoTuning.
Optional messageId: stringStart monitoring device parameter values.
When monitoring is started, Motion Master will begin and continue reading values from the device and send them back to a client at the specified interval on the given topic.
The request is made through the req/res socket MotionMasterReqResSocket, but the status messages will arrive on the pub/sub socket MotionMasterPubSubSocket.
The same monitoring can read both PDO and SDO values. PDO values will be updated on every Motion Master cycle (1ms). How fast SDO values will update depends on the number of SDOs being monitored. Motion Master reads the SDO values in a sequence, so, for example, if there are 10 SDOs and it takes 20ms to read a single SDO, it will take approximately 200ms for each SDO to get updated. IgH EtherCAT Master supports non-blocking SDO reading with a request to read and check the state of the request (one of not used, busy, failed, succeeded). A future version of Motion Master will likely leverage this and update SDO values out of order as each of the requests to update SDO succeeds. This should decrease the time it takes to read multiple SDOs. If a parameter is required to be updated more frequently, it should be mapped as a PDO.
Firmware versions >=5.2 support SDO complete access, but it is currently not being supported in Motion Master. With SDO complete access, RECORD and ARRAY subitems can be read with a single request.
The interval is given in microseconds.
The topic should be unique. The previous monitoring will stop if the given topic is reused. Clients can easily stop one another's monitoring by using the same topic. Prefixing topics with the client id or some other unique identifier is suggested.
When the monitoring request is received, Motion Master will mark all requested parameters as stale. The first time a parameter gets refreshed from a device, it'll be marked as not stale. Motion Master won't start publishing parameter values until all parameters are marked as not stale. This was done to satisfy the firmware test client applications.
Stopping the ongoing monitoring is done through the req/res socket using the request message ID of the initial start monitoring message stopMonitoringDeviceParameterValues.
Optional messageId: stringuse startCirculoEncoderNarrowAngleCalibrationProcedure instead
Optional messageId: stringStart offset detection.
Running offset detection differs for firmwares
For devices running firmware >=v5, Motion Master will execute multiple OS commands. Before initiating any command, the device is switched to Modes of operation -2 (Diagnostics mode), and it's put into the operation-enabled CiA402 state. The OS commands are then executed in the following order:
Motion Master will return an error if any of the following OS commands fail: open phase detection, phase order detection, commutation offset measurement. If other OS commands fail, Motion Master will continue with the procedure and only return a warning.
Once the commutation offset measurement command completes, it will update the following parameter values:
For devices running firmware <5, the same Modes of operation -2 is used, but it's named Commutation offset detection mode, and it will run as a single procedure as soon as the device is switched to CiA402 operation-enabled state. The end result is the same; the procedure will update 0x2001:00 and 0x2009:01 parameter values.
This request will turn the motor.
Optional messageId: stringStart open-loop field control.
The precondition for running the open-loop field control is to have a configured motor. No encoder configuration or offset detection is required.
Open-loop field control is started by changing the Modes of operation (0x6060) parameter value to -3 (Open-loop field mode) and setting the CiA402 state to Ready to switch on. After that, Motion Master will run several OS commands that configure the open-loop field control parameters:
After the configuration, Motion Master will switch the device to Operation enabled CiA402 state, and the profile will start.
While the open-loop field control is running, Motion Master will monitor the target reached bit in the statusword. When the target reached bit becomes 1, Motion Master will stop the procedure by changing the CiA402 state to Switched on.
Motion Master will return an error if the device goes out of the Operation enabled state before the target reached bit becomes 1. There is no timeout on the Motion Master side.
This request will turn the motor.
Optional messageId: stringStart OS command.
This request will execute an OS command and return the result as a byte array.
Motion Master will check if an OS command is already running and use a mutex to ensure only one OS command runs at a time.
This request can fail if the requested OS command is not supported.
Motion Master will check if the OS command has failed and return an error.
The OS command can timeout if it takes longer than the provided timeout in milliseconds, in which case Motion Master will return an error.
Optional messageId: stringuse startSystemIdentification instead
Optional messageId: stringStart signal generator.
This request will start one of the signal generators based on the previously set parameters with setSignalGeneratorParameters.
Signal generators are started by changing the mode of operation, putting the device into Operation enabled CiA402 state, and setting the target value. The mode of operation set depends on the type of signal generator and the selected controller:
Currently, the only profile type that the firmware supports is the ramp profile. Motion Master uses this profile type to construct and run the following signals: ramp, trapezoidal, and bidirectional. Sine wave is also a profile, but it is currently being generated on Motion Master alone. Firmwares >=5.2 will support generating and running sine wave profiles on devices themselves. This will enable lossless profile execution on possibly higher frequencies. Future Motion Master versions will switch to this method.
For the simple step response, Motion Master will only set the target value, wait for the specified holding duration, and then send a Quick Stop command.
The advanced step response is similar to the simple one, but, after the holding duration, it will set the new target multiple times depending on the shape, and then send a Quick Stop if the repeat option is set to NO. If repeat is set to YES, then the signal generator will run indefinitely, and the users must stop it manually.
Before running a profile, Motion Master will check if the device supports the profile modes by looking at 0x6502 Supported drive modes. If profile modes are not supported, then the profiles will be generated on Motion Master. This means the targets will be computed upfront. If profiles are supported, then the ramp, trapezoidal, and bidirectional signal generators are run in profile mode of operation. To prepare the signal generator for execution, Motion Master will set the following parameters:
The sine wave profile is generated upfront on Motion Master. Targets are computed for each master cycle (millisecond). Once the last computed target has been set, Motion Master will send a Quick Stop if repeat is set to NO.
For all signal generators, Motion Master will check the requested target against the currently set software position limits and, if necessary, alter it while returning a warning.
This request will turn the motor.
Optional messageId: stringStart system identification.
This request will run the system identification procedure, which identifies the plant model.
Pre-conditions: a configured motor and configured encoders.
The chirp signal that the procedure generates only uses the torque controller. The chirp signal is generated on Motion Master, and then, on every master cycle (1ms), the target torque value is set on a device. Motion Master will send a Quick Stop to a device after the last target value is set.
The request can fail for multiple reasons: the device is in the fault state, cannot set the op mode state, or the system identification fails because not enough data points have been collected. While running the chirp signal, the data points are collected, but due to potential communication lag, it can happen that the master doesn't collect enough data points. If more than 80% of data points are missing, the procedure will fail. If between 20%-80% of data points are missing, only a warning will be returned. The exact thresholds are subject to change.
Before computing the plant model data based on the collected data points, Motion Master will interpolate the missing data points. Plant model data is then computed and written to the plant_model.csv file on the device flash memory. The plant model file is later used to compute the PID values using computeAutoTuningGains and startFullAutoTuning. It's also used indirectly in startCoggingTorqueRecording when auto-config is turned on. Motion Master will also update the integral limit values in 0x2011: Velocity controller and 0x2012: Position controller during this procedure.
In future versions of the firmware, the chirp signal would be executed on the devices themselves, so no data points will be missing, and the system identification will be able to run at higher frequencies and with higher precision.
This request will turn the motor.
Optional messageId: stringuse stopDevice instead
Optional messageId: stringStop device.
Motion Master will use the current value of the Controlword object and set the command on it to Quick stop. It will then wait for up to 2 seconds for a device to enter one of the following CiA402 states: Switch on disabled, Operation enabled, Fault. This is achieved by periodically checking the value of the Statusword object. If the device fails to enter one of those states within the specified time, Motion Master will return a timeout or a quick stop failed error.
Optional messageId: stringStop full auto-tuning.
Motion Master has only one exit point for this procedure, which is after the computation algorithm ends. This means that, once stopped, the procedure will compute the gains, but Motion Master will not update the controller parameters. A previously started full auto-tuning request will complete with an aborted error.
Optional messageId: stringStop monitoring device parameter values.
The Message ID used for startMonitoringDeviceParameterValues uniquely identifies a monitoring and is used for stopping it.
Optional messageId: stringStop signal generator.
This request will send a Quick Stop command to the device.
Optional messageId: stringStore parameters.
Command the device to store the parameters into config.csv, then delay initially and subsequently check if the value of the Store parameters has changed to 1, indicating the successful completion.
https://www.synapticon.com/documentation/circulo/sw5.0/device_info/save_restore_config.html
Transition to CiA402 state.
This function will utilize the current value of the controlword and modify it to transition to the requested CiA402 state.
Only one transition will occur, except when the current CiA402 state is SWITCH_ON_DISABLED. In this case, the first transition is from SOD to RTSO, and then from RTSO to the requested CiA402 state.
The Statusword will be polled to check if the device has successfully transitioned to the requested CiA402 state. When transitioning to QSA, the Statusword will be checked against both QSA and SOD. This is necessary because the automatic transition from QSA to SOD can occur faster than the client's polling interval.
Unlock protected files.
This will enable the deletion of protected files. Protected files begin with a period, such as '.hardware_description'.
Optional messageId: stringOptional loadFromCache: booleanOptional requestTimeout: numberOptional messageId: stringOptional loadFromCache: booleanOptional requestTimeout: numberOptional messageId: stringOptional messageId: stringGenerated using TypeDoc
This class contains methods for making requests to Motion Master using the injected request/response socket.
Each request message defined in the proto file has a corresponding request method in this class. For some requests, like firmware installation, Motion Master will send progress messages until the firmware installation is complete.
A call to a request method will return an Observable of: (1) the corresponding status message, for example a call to
getDeviceInfowill return an instance ofMotionMasterMessage.Status.DeviceInfo, (2) request status - one of "succeeded," "failed," or "running.", and (3) request message id.If the request fails on Motion Master, the function will throw an error. It can also throw an error if the request times out.
Request methods have an optional messageId input parameter. If
messageIdis not provided, one will be generated before sending the request message to Motion Master. Status messages (responses) received from Motion Master that correspond to the previous request will have the samemessageIdas the one in the request. This is how we match requests with response messages in full-duplex asynchronous communication (WebSockets, ZeroMQ). Matching request/response by message id is inspired by the JSON-RPC 2.0 Specification.Almost all request methods have a mandatory
requestTimeoutinput parameter. This parameter specifies how long (in milliseconds) the client will wait for the status (response) messages corresponding to the previous request. If the status message is not received in due time, the request method will throw a timeout error. The error doesn't mean the request has failed on Motion Master, but rather that the client has given up waiting for the response(s). It's possible to stop some ongoing procedures on Motion Master with the corresponding stop messages, for example, StopFullAutoTuning.Example
How to handle a request method timeout error:
Request methods for a particular device, like
getDeviceParameterInfo, accept the type of request message as the first input parameter as defined in the proto file. ForgetDeviceParameterInfo, that'sMotionMasterMessage.Request.IGetDeviceParameterInfo. This type is extended (via type intersection) byDeviceRefObj. This is done in order to support multiple ways to reference a device. Motion Master only supports device addresses, which it re-generates for each device on power cycle. Because device addresses can change, for scripts and applications, it's preferred to use a device reference that won't change. The device serial number in the hardware description file uniquely identifies the device and doesn't change. This is what each request message is extended with. Before sending the request message to Motion Master, the device address gets resolved and is set on the request message. Besides the device address and device serial number, devices can be referenced by position (sequence number in the network chain).It is ensured that the Observable returned from a call to the request method will eventually complete, so a call to unsubscribe is not required. The Observable will complete when the request status is either "succeeded" or "failed," or it will complete (error) due to a timeout. Finding out if a request has completed, failed, or is still ongoing is different for each request - it depends on the status messages, see requestStatusResolver. Request methods handle this and for each request, they will emit status messages with one of "succeeded," "failed," or "running" request statuses.
Besides the request methods, this class contains many helper methods such as the ones for getting and setting device parameter values and saving all parameters, which involves complex logic like multiple repeating requests to determine if saving all parameters has completed successfully.