ℹ️ Motion Master v5.x.x and subsequent versions are built from this repository. However, Motion Master v4.x.x, which exclusively supports IgH EtherCAT Master, continues to be built from the igh-release branch in the old repository.

🌱 This repository is the successor to synapticon/motion-master.

Overview

Motion Master is a C++ application that communicates with SOMANET devices over fieldbuses and provides a WebSocket API for client interaction. It also includes a collection of libraries designed for efficient and easy-to-use access to the full range of features supported by general EtherCAT devices, as well as SOMANET-specific functionality.

With Motion Master, clients can perform tasks such as device listing, data exchange, and file management, as well as execute more advanced procedures like encoder calibration and auto-tuning. This makes it a versatile platform for both basic operations and complex system workflows.

Getting Started

Clone this repository along with all its submodules:

git clone --recurse-submodules -j8 git@github.com:synapticon/motion_master.git

Note: If you've already cloned the repository but haven't yet initialized or updated its submodules, you can do so with the following command: git submodule update --init --recursive.

You can configure and build the project using the following commands:

./tools/prepare-debian.sh
cmake --preset x64-linux-debug
cmake --build --preset x64-linux-debug --target motion_master --parallel

Now run it as follows:

./out/build/x64-linux-debug/apps/motion_master/motion_master --driver=soem --mac=20:88:10:7C:62:6D --req-res-port=63524 --pub-sub-port=63525

The previous command will use the SOEM EtherCAT master driver, initializing on the network interface with the provided MAC address (20:88:10:7C:62:6D). It will bind the server to the specified WebSocket ports: 63524 for request-response communication and 63525 for publish-subscribe communication. These WebSocket ports are optional; if not specified, the default ports 63524 and 63525 will be used.

We recommend using Visual Studio Code with the following extensions installed:

⚠️ Important: The verified compatible version of the CMake Tools extension for this repository is 1.20.53.

Visual Studio Code CMake Tools will automatically initialize Vcpkg and and install the libraries specified in the vcpkg.json file.

Testing

./tools/prepare-debian.sh
cmake --preset x64-linux-debug
cmake --build --parallel --preset x64-linux-debug --target=motion_master
ctest --preset x64-linux-debug --target motion_master

Style Guide

We follow the Google C++ Style Guide. For a concise summary tailored to this project, refer to our local style guide.

You can run Google's linter on this repository using the following command:

python -m pip install cpplint

python -m cpplint ./apps/* ./libs/*

To automatically format all source code files in the motion_master directory, use the following command:

./tools/format.sh ./apps/motion_master

Releasing with a GitHub Self-Hosted Runner

This approach provides greater control over the environment, tools, and Vcpkg caching.

Prerequisites:

Windows 11
Visual Studio 2022, CMake, and Ninja
Git and Docker installed
GitHub account with access to the Synapticon organization
Docker Hub account with permission to push images to the Synapticon organization

To temporarily enable cl.exe in your PowerShell 7 (x64) session, follow these steps:

Open PowerShell 7 (x64).
Run the following command to initialize the Visual Studio environment:

cmd /c '"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x64 && powershell'
Once the new PowerShell session starts, verify that cl.exe is available by running:

cl

ℹ️ The previous steps are necessary because the Developer Command Prompt for VS 2022 may default to the 32-bit toolset, causing linker failures in 64-bit builds. You can verify this by running cl and checking if the output includes for x86.

To start the self-hosted runner, navigate to the directory where you enabled the Visual Studio compiler, then run the following command in the terminal:

cd actions-runner

.\run.cmd

Below is a one-line PowerShell script (run.ps1) that sets up the Visual Studio environment and launches the self-hosted runner:

cmd /c '"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x64 && powershell -NoExit -Command "& {cd actions-runner; .\run.cmd}"'

Next, navigate to the GitHub workflow and trigger it.

Checking DLL Dependencies

Open the Developer PowerShell for Visual Studio 2022.
Navigate to the cloned motion_master repository.
Configure and build the project according to the previous instructions.
Proceed with the following steps:

cd ./out/build/x64-windows-release/apps/motion_master/

dumpbin /dependents motion_master.exe

Another approach is to use Dependency Walker.

An efficient method to check for missing DLL dependencies and test Motion Master on a newly installed operating system is to use Windows Sandbox.

Docker

OBLAC Drives v25.x releases use Motion Master v5.x, which is based on SOEM rather than IgH EtherCAT Master. To run Motion Master v5.x as a Docker container on the OBLAC Box, make sure to stop and disable the EtherCAT (IgH EtherCAT Master) service.

If the MM_MAC environment variable is not set when starting the Docker container, the entrypoint script will automatically extract the MAC address from the /etc/ethercat.conf file. This simplifies setup, requiring only that the EtherCAT service be stopped, with no additional steps needed when starting the container.

There are two methods for accessing the OBLAC Box to perform this task:

Connect the OBLAC Box to a monitor and keyboard. All OBLAC Boxes use the default username (administrator) and password (administrator).
SSH into the OBLAC Box. SSH access using a username and password is disabled. Instead, you must use the private key, which is unique to each box.

Once you have access, stop and disable the current Motion Master Docker container and EtherCAT services by running the following commands:

docker stop motion-master && docker rm motion-master
sudo systemctl stop ethercat-watchdog && sudo systemctl disable ethercat-watchdog
sudo systemctl stop ethercat && sudo systemctl disable ethercat

Alternatively, use the following command, replacing id_rsa with the OBLAC Box's private key and oblac-drives-7dc95497 with the OBLAC Box's hostname:

ssh -t -i id_rsa administrator@oblac-drives-7dc95497 "docker stop motion-master && docker rm motion-master && sudo systemctl stop ethercat-watchdog && sudo systemctl disable ethercat-watchdog && sudo systemctl stop ethercat && sudo systemctl disable ethercat"

When prompted for a password, enter: administrator

⚠️ Important: Ensure that you are running the latest version of the OBLAC Drives Update Service (v3.0.6) before proceeding to the next step.

You can now open the OBLAC Drives Update Service and install the desired v25.x release of the OBLAC Drives.

To manually start the Docker container and specify the MAC address, use the following command:

docker run \
   -d \
   --restart always \
   --name motion-master \
   --network host \
   --privileged \
   -e MM_MAC="74:56:3C:BF:34:12" \
   synapticon/motion-master:v5.0.0-beta.35

If you need to revert to using the IgH EtherCAT master, execute the opposite commands:

docker stop motion-master && docker rm motion-master
sudo systemctl start ethercat-watchdog && sudo systemctl enable ethercat-watchdog
sudo systemctl start ethercat && sudo systemctl enable ethercat

Open the OBLAC Drives Update Service and install the desired v24.x release of the OBLAC Drives.

Flashing Integro NetX Firmware via JTAG

Download and install the SEGGER J-Link Software.
Add the J-Link installation directory (C:\Program Files\SEGGER\JLink_V854) to your system PATH environment variable. This allows you to run J-Link tools from the command line.
Connect your Integro device to the JTAG-ARM adapter, and then connect the adapter to your computer.

Firmware Package Contents

Each firmware package contains a file named com_*.bin. This file is a ZIP archive. Extract it using a tool like 7-Zip to obtain two files:

FIRMWARE.NAI — Application firmware for the APP CPU on the netX SoC, developed by Synapticon.
FIRMWARE.NXI — Communication firmware for the COM CPU on netX devices.

Rename these files as follows:

FIRMWARE.NAI → nai.bin
FIRMWARE.NXI → nxi.bin

Flashing Procedure

Create a batch script named flasher.bat with the following content:

JLink -device netX90_Com -if JTAG -speed 1000 -AutoConnect 1 -JTAGConf 0,0 -CommanderScript cmdfile.jlink

Also create a J-Link command script cmdfile.jlink with the following commands:

 -Link
reset
halt
loadbin nai.bin 0x00200000
loadbin nxi.bin 0x00103000
reset
go
exit

Now, run the flashing script by executing:

.\flasher.bat