CLI utility to work with DCC equpied locomotives and wagons.
- Create a global configuration file
nano ~/.loco.yaml- Adjust & put configuration details
server:
type: "z21"
address: "192.168.0.111"
port: "21105"You can toggle a locomotive function (e.g. F0-F28) directly over a Lenz LAN
TCP connection (default port 5550) using the fn send subcommand:
# Toggle F3 on locomotive 3 (turn on)
$ loco fn send -l 3 -f 3 -o
# Turn F3 off
$ loco fn send -l 3 -f 3 --on=false
# Specify a different host (port is fixed to 5550)
$ loco fn send -H 192.168.0.50 -l 17 -f 0 -oFlags:
-H, --hostLenz command station host (port 5550 is fixed)-l, --locoLocomotive DCC address-f, --fnFunction number to toggle-o, --onTurn the function on (use--on=falseto turn off)-t, --timeoutConnection timeout in seconds-v, --debugEnable debug logging (shows the raw frame bytes)
The frame sent follows the XpressNet LAN_X_SET_LOCO_FUNCTION structure:
E4 F8 <AdrLSB> <AdrMSB> <GroupType> <GroupState> <XOR>.
$ loco cv get cv1,cv2
cv1=17
cv2=2$ loco cv get cv52-53=0, cv1, cv5
cv1=17
cv5=255
cv52=0
cv53=0$ loco cv get cv1-cv255
cv1=17
cv2=2
# ...
cv255=5$ loco cv get cv1
17# -t: track type, could be pom or prog
# -l: locomotive address
$ loco cv get cv2 -t pom -l 17
5
# when the "-l" is not specified the programming track is automatically chosen
$ loco cv get cv2
5Logging messages are sent via stderr, results are in stdout.
$ loco cv get -v cv52-53=0, cv1, cv5
DEBU[0000] Reading configuration files
DEBU[0000] Initializing command station
DEBU[0000] z21.sendAndAwait([]byte = [1001 0 1000000 0 100011 10001 0 0 110010])
DEBU[0001] Marking programmng track as to be powered off
cv1=17
DEBU[0001] z21.sendAndAwait([]byte = [1001 0 1000000 0 100011 10001 0 100 110110])
DEBU[0002] Marking programmng track as to be powered off
cv5=255
DEBU[0002] z21.sendAndAwait([]byte = [1001 0 1000000 0 100011 10001 0 110011 1])
DEBU[0003] Marking programmng track as to be powered off
cv52=0
DEBU[0003] z21.sendAndAwait([]byte = [1001 0 1000000 0 100011 10001 0 110100 110])
DEBU[0004] Marking programmng track as to be powered off
cv53=0
DEBU[0004] Restoring power on programming trackNotice: Timeout = 0 does not mean no timeout at all, it means 0 seconds, so all commands would fail immediately
$ loco cv get cv52-53=0, cv1, cv5 --timeout 0
cv1=ERROR
ERRO[0000] cannot read CV: no response or unrecognized response
cv5=ERROR
ERRO[0001] cannot read CV: no response or unrecognized response
cv52=ERROR
ERRO[0001] cannot read CV: no response or unrecognized response
cv53=ERROR
ERRO[0002] cannot read CV: no response or unrecognized response
Error: cannot read CV: no response or unrecognized response
Usage:
loco cv get [flags]
Flags:
-v, --debug Increase verbosity to the debug level
-h, --help help for get
-l, --loco uint8 Use locomotive under specific address
--timeout uint16 Connection timeout (default 10)
-t, --track string Track type: 'pom' for programming on main, 'prog' for programming track, or empty for automatic selection
--verify Verify the value after writtingCLI command gives an advantage over UI interfaces with a possibility of scripting. Backup & Restore is a natural use case of using CLI. You can experiment with various locomotive settings having multiple CV settings and quickly move between them by massivly dumping and loading the values.
$ cat ./examples/cv-read.example.txt
cv1
cv2
cv3-cv4
$ cat ./examples/cv-read.example.txt | loco cv get -- -
cv1=17
cv2=2
cv3=34
cv4=25# Receive CV1, CV2, CV3, CV4 and save to backup-cv.txt file
$ loco cv get cv2-cv4 > backup-cv.txt
# Then restore it to a locomotive from a backup-cv.txt file anytime
$ cat backup-cv.txt | loco cv set -v -- -# list functions that are in "on" state
$ loco fn list -l 3
No active functions
# toggle F0 and F5 to "on"
$ loco fn set 0 -l 3
$ loco fn set 5 -l 3
# list functions, there should be two listed that we turned "on"
$ loco fn list -l 3
F0 = On
F5 = On
# now we turn off F5
$ loco fn set 5 -l 3 --off
# so the F0 should be listed only
$ loco fn list -l 3
F0 = On