Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


SCMDCTL(1)                  General Commands Manual                 SCMDCTL(1)

NAME
     scmdctl - Command line utility to interact with a Sparkfun Serial
     Controlled Motor Driver

SYNOPSIS
     scmdctl [-dhl] [-b baud rate] [-s SPI slave address] device identify
             [module]
     scmdctl [-dhl] [-b baud rate] [-s SPI slave address] device diagnostics
             [module]
     scmdctl [-dhl] [-b baud rate] [-s SPI slave address] device motor
             get | set | invert | bridge | enable | disable
             module ([get] | set | invert | bridge) A | B (set | invert)
             value (set)
     scmdctl [-dhl] [-b baud rate] [-s SPI slave address] device read_register
             module register [register_end]
     scmdctl [-dhl] [-b baud rate] [-s SPI slave address] device
             write_register module register_value
     scmdctl [-dhl] [-b baud rate] [-s SPI slave address] device restart
     scmdctl [-dhl] [-b baud rate] [-s SPI slave address] device re-enumerate
     scmdctl [-dhl] [-b baud rate] [-s SPI slave address] device update_rate
             get | set | force rate (set)
     scmdctl [-dhl] [-b baud rate] [-s SPI slave address] device expansion_bus
             get | set 50kHz | 100kHz | 400kHz (set)
     scmdctl [-dhl] [-b baud rate] [-s SPI slave address] device lock
             get | lock | unlock
             local_user | local_master | global_user | global_master
     scmdctl [-dhl] [-b baud rate] [-s SPI slave address] device spi_read_one

DESCRIPTION
     The scmdctl 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.

     The options are as follows:

     -d debug mode

     -h displays help

     -l displays the register names and numbers

     -b baud rate when interacting with a SCMD using a tty uart

     -s SPI slave address when interacting with a SCMD using SPI userland mode

     The SCMD device may be a uart tty(4), a spi(4), device or a scmd(4)
     device.  The latency is very different depending on which device is used:
     +------------+----------------------------------+------------------------------------------------------------------+
     |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 |
     +------------+----------------------------------+------------------------------------------------------------------+
     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.

     The commands are as follows:

     identify [module]
             Print identifying information about the module on a specific
             device.

     diagnostics [module]
             Print the diagnostics registers for a module.

     motor get|set|invert|bridge|enable|disable
             module([get]|set|invert|bridge) A|B(set|invert) value(set)
             Interact with the motors.  The subcommand arguments are as
             follows:
             +-----------+------------------------+-----------------------------------------------------------+
             |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                      |
             +-----------+------------------------+-----------------------------------------------------------+
     read_register module register [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.

     write_register module register 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.

     restart
             Issue a restart directive to the SCMD.

     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.

     update_rate get|set|force 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.

     expansion_bus get|set 50kHz|100kHz|400kHz(set)
             Set the speed of the expandsion I2C bus.

     lock get|lock|unlock 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.

     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.

EXAMPLES
           scmdctl /dev/dtyU0 identify

     Perform a identify command against the serial device /dev/dtyU0 and
     return the results.

           scmdctl /dev/spi0 motor get 0

     Get the status of the motors on module 0 by accessing the SCMD device
     using userland SPI.

           scmdctl /dev/scmd0 motor set 1 B 127
           scmdctl /dev/scmd0 motor invert 1 B

     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.

           scmdctl /dev/scmd0 read_register 0 0x00 4
           scmdctl /dev/scmd0 read_register 0 FID CONFIG_BITS

     Read the first four registers on the master SCMD module using the kernel
     scmd(4) device.  Both of those two examples return the same information.

SEE ALSO
     iic(4), spi(4), scmdi2c(4), scmdspi(4),

HISTORY
     The scmdctl utility first appeared in NetBSD 10.0.

AUTHORS
     The scmdctl utility was written by Brad Spencer <brad@anduin.eldar.org>.

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
     scmdctl(1) command can hang in this mode.  It is also possible and likely
     that the scmdctl(1) command will hang after a restart is performed in
     this mode.

     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.

     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.

     No attempt has been made with scmdctl(1) to make the failsafe functions
     of the SCMD device available in any convient manor.

NetBSD 10.99                   December 1, 2021                   NetBSD 10.99