Motion Master Client Examples

This repository provides TypeScript/JavaScript examples for interacting with Synapticon's Motion Master server application to configure and control SOMANET devices.

Building

Node on the PATH

If npx is not found, Node is probably installed through nvm, which is only available once its init script has been sourced. Once per terminal session:

source ~/.nvm/nvm.sh && nvm use --lts

To have it loaded automatically, add nvm's init lines to your shell profile:

echo 'export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"' >> ~/.zshrc

Running the examples in Docker (see below) sidesteps this entirely — the image brings its own Node.

Dependencies

Clone this repository and install its dependencies:

git clone https://github.com/synapticon/motion-master-client-examples.git
cd motion-master-client-examples
npm install

To transpile from TypeScript to JavaScript, use the following command:

npm run build

The resulting JavaScript files will be located in the dist folder.

Running

Before executing any scripts, ensure to set the MOTION_MASTER_HOSTNAME environment variable. For example, if the Motion Master process runs at 192.168.1.112, you have two options:

1. Create a .env file in the repository root with MOTION_MASTER_HOSTNAME=192.168.1.112.
2. Run a script directly by setting the variable inline: MOTION_MASTER_HOSTNAME=192.168.1.112 node ./dist/request/get-devices.rx.js.

The advantage of using the .env file is that all scripts will consistently use the specified hostname without needing to set the variable each time.

To log all incoming and outgoing messages from Motion Master, set the ROAR_LOG=true environment variable when running your scripts.

Here's an example .env file configuration:

MOTION_MASTER_HOSTNAME=192.168.1.112
ROARR_LOG=true

Alternatively, you can run TypeScript files directly without transpiling using ts-node:

npx ts-node ./src/request/get-devices.rx.ts

Command line arguments

All commands associated with a specific device require the --device-ref option, along with other specific arguments. To view detailed help documentation for any command, use the --help option. For example:

npx ts-node ./src/request/upload.ts --help
Usage: upload [options] <index> <subindex> [loadFromCache]

Arguments:
  index                          object index in hexadecimal notation
  subindex                       object subindex in hexadecimal notation
  loadFromCache                  load parameter values from the Motion Master cache (choices: "true", "false", default: false)

Options:
  -d, --device-ref <value>       position, address, or serial number (default: 0 position represents the first device in a network chain)
  -t, --request-timeout <value>  after sending a request, how long will the client wait for Motion Master to send the status message back
  -m, --message-id <value>       the message ID, which uniquely identifies the request, will be generated by the client library if not specified
  -h, --help                     display help for command

Here is an example of how to read the drive temperature:

npx ts-node ./src/request/upload.ts --device-ref=1 0x2031 0x01

Monitoring

To monitor output data and save it to both stdout and a file (data.csv), use:

node ./dist/start-monitoring.js --device-ref=1 | tee data.csv

Running in Docker

docker-compose.yml defines a long-lived container named motion-master-client with this repository mounted into it, so you edit files on your machine and run them inside the container. It supersedes running docker build / docker run by hand — Compose still builds from the Dockerfile, it just wires up the mounts, the hostname and the restart policy for you.

Note that this container is only the client. Motion Master itself needs the EtherCAT NIC and runs outside the container. On macOS it has to run natively on the host: a container there lives inside a Linux VM and cannot see the Mac's network interfaces at all, not even with --privileged --network host.

Run all of the following from the repository root.

Start it, building the image on first use:

docker compose up -d

Run a script inside it:

docker compose exec client npx ts-node src/request/get-devices.promise.ts

Compiled JavaScript works too, and is faster to start:

docker compose exec client node dist/request/get-devices.promise.js

Open an interactive shell:

docker compose exec client sh

Stop and resume the container. Both preserve everything — the repository is a bind mount, and packages installed inside live in a named volume:

docker compose stop

docker compose start

Remove the container. The node_modules volume survives this; add -v to delete that too:

docker compose down

Snapshot the container into an image, for a restore point before down or an upgrade:

docker commit motion-master-client mmce:backup

Hostname inside the container

MOTION_MASTER_HOSTNAME defaults to host.docker.internal, which resolves to the machine running Docker. Never use localhost here — inside a container that is the container itself. Point it at another machine by setting it before starting:

MOTION_MASTER_HOSTNAME=192.168.1.112 docker compose up -d

A .env file in the repository root is deliberately not copied into the image, so pass the hostname this way instead.

What persists, and what does not

State	Where it lives	Survives stop/start	Survives down
Your source files and any output a script writes	bind mount, i.e. your working tree	yes	yes
Packages installed inside the container	named volume node_modules	yes	yes, unless down -v
Anything else in the container filesystem	container layer	yes	no — docker commit first

Because the repository is mounted, files a script writes (recorded CSVs, generated plots) appear directly in your working tree rather than disappearing with the container.

node_modules is deliberately kept out of the mount: the host's copy is built for the host's platform, and letting it shadow the image's Linux dependencies breaks any native module.

Developing

To watch .ts files for changes and automatically transpile, use:

npm run watch