286 lines
8.8 KiB
Groff
286 lines
8.8 KiB
Groff
.\" $NetBSD: scmdctl.1,v 1.1 2021/12/07 17:39:55 brad 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 convient 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 is 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 convient manor.
|