path: root/static/netbsd/man1/scmdctl.1

.\" $NetBSD: scmdctl.1,v 1.2 2025/07/08 17:56:45 gutteridge Exp $
.\"
.\" Copyright (c) 2021 Brad Spencer <brad@anduin.eldar.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd December 1, 2021
.Dt SCMDCTL 1
.Os
.Sh NAME
.Nm scmdctl
.Nd Command line utility to interact with a Sparkfun Serial Controlled Motor Driver
.Sh SYNOPSIS
.Nm scmdctl
.Op Fl dhl
.Op Fl b Ar baud rate
.Op Fl s Ar SPI slave address
.Ar device
.Ar identify
.Op Ar module
.Nm scmdctl
.Op Fl dhl
.Op Fl b Ar baud rate
.Op Fl s Ar SPI slave address
.Ar device
.Ar diagnostics
.Op Ar module
.Nm scmdctl
.Op Fl dhl
.Op Fl b Ar baud rate
.Op Fl s Ar SPI slave address
.Ar device
.Ar motor
.Ar get \&| Ar set \&| Ar invert \&| Ar bridge \&| Ar enable \&| Ar disable
.Ar module ([get] \&| Ar set \&| Ar invert \&| bridge)
.Ar A \&| Ar B (set \&| Ar invert)
.Ar value (set)
.Nm scmdctl
.Op Fl dhl
.Op Fl b Ar baud rate
.Op Fl s Ar SPI slave address
.Ar device
.Ar read_register
.Ar module
.Ar register
.Op Ar register_end
.Nm scmdctl
.Op Fl dhl
.Op Fl b Ar baud rate
.Op Fl s Ar SPI slave address
.Ar device
.Ar write_register
.Ar module
.Ar register_value
.Nm scmdctl
.Op Fl dhl
.Op Fl b Ar baud rate
.Op Fl s Ar SPI slave address
.Ar device
.Ar restart 
.Nm scmdctl
.Op Fl dhl
.Op Fl b Ar baud rate
.Op Fl s Ar SPI slave address
.Ar device
.Ar re-enumerate 
.Nm scmdctl
.Op Fl dhl
.Op Fl b Ar baud rate
.Op Fl s Ar SPI slave address
.Ar device
.Ar update_rate
.Ar get \&| Ar set \&| Ar force
.Ar rate (set)
.Nm scmdctl
.Op Fl dhl
.Op Fl b Ar baud rate
.Op Fl s Ar SPI slave address
.Ar device
.Ar expansion_bus
.Ar get \&| set
.Ar 50kHz \&| Ar 100kHz \&| 400kHz (set)
.Nm scmdctl
.Op Fl dhl
.Op Fl b Ar baud rate
.Op Fl s Ar SPI slave address
.Ar device
.Ar lock
.Ar get \&| Ar lock \&| Ar unlock
.Ar local_user \&| Ar local_master \&| Ar global_user \&| global_master
.Nm scmdctl
.Op Fl dhl
.Op Fl b Ar baud rate
.Op Fl s Ar SPI slave address
.Ar device
.Ar spi_read_one 
.Sh DESCRIPTION
The
.Nm
utility interacts with a Sparkfun Serial Controlled Motor Driver (SCMD) and provides
a set of convenient commands for most of the functions that the SCMD has.
.Pp
The options are as follows:
.Bl -tag -width indent
.It Fl d Ar debug mode
.It Fl h Ar displays help
.It Fl l Ar displays the register names and numbers
.It Fl b Ar baud rate when interacting with a SCMD using a tty uart
.It Fl s Ar SPI slave address when interacting with a SCMD using SPI userland mode
.El
.Pp
The SCMD device may be a uart
.Xr tty 4 ,
a
.Xr spi 4 ,
device or a
.Xr scmd 4
device.  The latency is very different depending on which device is used:
.TS
box tab(:);
l | l | l
= | = | =
l | l | l
l | l | l
- | - | -
l | l | l
l | l | l
- | - | -
l | l | l
l | l | l.
Device:Latency:Description
/dev/ttyXXX:High for local modules and:This uses the built in command line parser
:very high for remote modules:in the SCMD device and must parse the text input and output
/dev/spiX:Reasonable for local modules and:This uses userland SPI access and must deal with
:high for remote modules:the view port in userland for remote modules
/dev/scmdX:Low for local modules and:The kernel handles the view port access for
:reasonable for remote modes:remote modules and presents a linear register map of all modules
.TE
.Pp
In all cases the module argument is 0 to 16, with 0 being the master module.
In cases where the module argument is optional, it defaults to 0.
Each SCMD module can have two motors, labeled A and B.  If the module
is bridged then only actions on the A motor have any effect.
.Pp
The commands are as follows:
.Bl -tag -width indent
.It Ar identify Ar [module]
Print identifying information about the module on a specific device.
.It Ar diagnostics Ar [module]
Print the diagnostics registers for a module.
.It motor Ar get|set|invert|bridge|enable|disable Ar module([get]|set|invert|bridge) Ar A|B(set|invert) Ar value(set)
Interact with the motors.  The subcommand arguments are as follows:
.TS
box tab(:);
l | l | l
= | = | =
l | l | l
- | - | -
l | l | l
l | l | l
l | l | l
- | - | -
l | l | l
l | l | l
- | - | -
l | l | l
- | - | -
l | l | l
- | - | -
l | l | l.
Subcommand:Arguments:Description
get:[module]:Gets details about the motors
set:module:Set the power value for a motor
:A or B:
:value from -127 to 127:
invert:module:Inverts the power value for a motor
:A or B:
bridge:module:Bridge motors A and B on a module together
enable::Enable the driver, apply the directed power to the motors
disable::Disable the driver, remove all power
.TE
.It read_register Ar module Ar register Ar [register_end]
Read the registers from a module starting with register and optionally
ending with register_end.  The values for register and register_end are
in the range from 0 to 126 in either decimal or hex or they may be a
named register.
.It write_register Ar module Ar register Ar value
Write a value to a register on a module.  The register values are from
0 to 126 in either decimal or hex or may be a named register name.  The
value that can be written to a register is 0 to 255 either in decimal or
hex.
.It restart 
Issue a restart directive to the SCMD.
.It re-enumerate
Issue a re-enumeration command to the SCMD.  This will cause the master module
to search the expansion bus I2C chain for additional modules.
.It update_rate Ar get|set|force Ar rate(set)
Set the update rate in which the master module updates the remote modules.  If
rate is set to 0 then updates will only happen when force is done.
.It expansion_bus Ar get|set Ar 50kHz|100kHz|400kHz(set)
Set the speed of the expandsion I2C bus.
.It lock Ar get|lock|unlock Ar local_user|local_master|global_user|global_master
View lock or unlock one of the locks on the SCMD device.  Global locks are
sent to any attached SCMD device on the expansion bus, and local locks apply
only to the master module.
.It spi_read_one
This command is usable only in SPI userland mode and performs a single receive
in the hopes of unsticking the SCMD device.
.El
.Sh EXAMPLES
.Pp
.Dl "scmdctl /dev/dtyU0 identify"
.Pp
Perform a identify command against the serial device /dev/dtyU0 and return
the results.
.Pp
.Dl "scmdctl /dev/spi0 motor get 0"
.Pp
Get the status of the motors on module 0 by accessing the SCMD device using
userland SPI.
.Pp
.Dl "scmdctl /dev/scmd0 motor set 1 B 127"
.Dl "scmdctl /dev/scmd0 motor invert 1 B"
.Pp
Set the power value of the B motor on module 1 to 127 and then invert the power.
Note that the values returned by a get against module 1 will still show the
positive value 127, but will indicate that the motor power is inverted.
.Pp
.Dl "scmdctl /dev/scmd0 read_register 0 0x00 4"
.Dl "scmdctl /dev/scmd0 read_register 0 FID CONFIG_BITS"
.Pp
Read the first four registers on the master SCMD module using the kernel
.Xr scmd 4
device.  Both of those two examples return the same information.
.Sh SEE ALSO
.Xr iic 4 ,
.Xr spi 4 ,
.Xr scmdi2c 4 ,
.Xr scmdspi 4 ,
.Sh HISTORY
The
.Nm
utility first appeared in
.Nx 10.0 .
.Sh AUTHORS
.An -nosplit
The
.Nm
utility was written by
.An Brad Spencer Aq Mt brad@anduin.eldar.org .
.Sh BUGS
When accessing the SCMD devices using tty uart access, it is not really
possible to deal with line noise and there are no safety checks built into
the device to help with this.  It is entirely possible that the
.Xr scmdctl 1
command can hang in this mode.  It is also possible and likely that the
.Xr scmdctl 1
command will hang after a restart is performed in this mode.
.Pp
Performing a read in SPI mode, either in the kernel or in userland, is a
little odd with the SCMD device.  There is a requirement that a dummy or
null read be performed and if this does not work as expected further reads
will not work.  The spi_read_one command is an attempt to unstick
a stuck SCMD device.
.Pp
If the SPI or I2C pins are not set up when the kernel device driver attaches
it will not be able to display information about the device, but it will also
not be able to ask the device how many modules exist and will more or less
assume that only the master node exists.  If further set up is required after
the device attaches, a re-enumeration should be performed before any actions
are done to the motors.
.Pp
No attempt has been made with
.Xr scmdctl 1
to make the failsafe functions of the SCMD device available in any convenient
manner.