1.\" $NetBSD: scmdctl.1,v 1.1 2021/12/07 17:39:55 brad Exp $ 2.\" 3.\" Copyright (c) 2021 Brad Spencer <brad@anduin.eldar.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd December 1, 2021 18.Dt SCMDCTL 1 19.Os 20.Sh NAME 21.Nm scmdctl 22.Nd Command line utility to interact with a Sparkfun Serial Controlled Motor Driver 23.Sh SYNOPSIS 24.Nm scmdctl 25.Op Fl dhl 26.Op Fl b Ar baud rate 27.Op Fl s Ar SPI slave address 28.Ar device 29.Ar identify 30.Op Ar module 31.Nm scmdctl 32.Op Fl dhl 33.Op Fl b Ar baud rate 34.Op Fl s Ar SPI slave address 35.Ar device 36.Ar diagnostics 37.Op Ar module 38.Nm scmdctl 39.Op Fl dhl 40.Op Fl b Ar baud rate 41.Op Fl s Ar SPI slave address 42.Ar device 43.Ar motor 44.Ar get \&| Ar set \&| Ar invert \&| Ar bridge \&| Ar enable \&| Ar disable 45.Ar module ([get] \&| Ar set \&| Ar invert \&| bridge) 46.Ar A \&| Ar B (set \&| Ar invert) 47.Ar value (set) 48.Nm scmdctl 49.Op Fl dhl 50.Op Fl b Ar baud rate 51.Op Fl s Ar SPI slave address 52.Ar device 53.Ar read_register 54.Ar module 55.Ar register 56.Op Ar register_end 57.Nm scmdctl 58.Op Fl dhl 59.Op Fl b Ar baud rate 60.Op Fl s Ar SPI slave address 61.Ar device 62.Ar write_register 63.Ar module 64.Ar register_value 65.Nm scmdctl 66.Op Fl dhl 67.Op Fl b Ar baud rate 68.Op Fl s Ar SPI slave address 69.Ar device 70.Ar restart 71.Nm scmdctl 72.Op Fl dhl 73.Op Fl b Ar baud rate 74.Op Fl s Ar SPI slave address 75.Ar device 76.Ar re-enumerate 77.Nm scmdctl 78.Op Fl dhl 79.Op Fl b Ar baud rate 80.Op Fl s Ar SPI slave address 81.Ar device 82.Ar update_rate 83.Ar get \&| Ar set \&| Ar force 84.Ar rate (set) 85.Nm scmdctl 86.Op Fl dhl 87.Op Fl b Ar baud rate 88.Op Fl s Ar SPI slave address 89.Ar device 90.Ar expansion_bus 91.Ar get \&| set 92.Ar 50kHz \&| Ar 100kHz \&| 400kHz (set) 93.Nm scmdctl 94.Op Fl dhl 95.Op Fl b Ar baud rate 96.Op Fl s Ar SPI slave address 97.Ar device 98.Ar lock 99.Ar get \&| Ar lock \&| Ar unlock 100.Ar local_user \&| Ar local_master \&| Ar global_user \&| global_master 101.Nm scmdctl 102.Op Fl dhl 103.Op Fl b Ar baud rate 104.Op Fl s Ar SPI slave address 105.Ar device 106.Ar spi_read_one 107.Sh DESCRIPTION 108The 109.Nm 110utility interacts with a Sparkfun Serial Controlled Motor Driver (SCMD) and provides 111a set of convient commands for most of the functions that the SCMD has. 112.Pp 113The options are as follows: 114.Bl -tag -width indent 115.It Fl d Ar debug mode 116.It Fl h Ar displays help 117.It Fl l Ar displays the register names and numbers 118.It Fl b Ar baud rate when interacting with a SCMD using a tty uart 119.It Fl s Ar SPI slave address when interacting with a SCMD using SPI userland mode 120.El 121.Pp 122The SCMD device may be a uart 123.Xr tty 4 , 124a 125.Xr spi 4 , 126device or a 127.Xr scmd 4 128device. The latency is very different depending on which device is used: 129.TS 130box tab(:); 131l | l | l 132= | = | = 133l | l | l 134l | l | l 135- | - | - 136l | l | l 137l | l | l 138- | - | - 139l | l | l 140l | l | l. 141Device:Latency:Description 142/dev/ttyXXX:High for local modules and:This uses the built in command line parser 143:very high for remote modules:in the SCMD device and must parse the text input and output 144/dev/spiX:Reasonable for local modules and:This uses userland SPI access and must deal with 145:high for remote modules:the view port in userland for remote modules 146/dev/scmdX:Low for local modules and:The kernel handles the view port access for 147:reasonable for remote modes:remote modules and presents a linear register map of all modules 148.TE 149.Pp 150In all cases the module argument is 0 to 16, with 0 being the master module. 151In cases where the module argument is optional, it defaults to 0. 152Each SCMD module can have two motors, labeled A and B. If the module 153is bridged then only actions on the A motor have any effect. 154.Pp 155The commands are as follows: 156.Bl -tag -width indent 157.It Ar identify Ar [module] 158Print identifying information about the module on a specific device. 159.It Ar diagnostics Ar [module] 160Print the diagnostics registers for a module. 161.It motor Ar get|set|invert|bridge|enable|disable Ar module([get]|set|invert|bridge) Ar A|B(set|invert) Ar value(set) 162Interact with the motors. The subcommand arguments are as follows: 163.TS 164box tab(:); 165l | l | l 166= | = | = 167l | l | l 168- | - | - 169l | l | l 170l | l | l 171l | l | l 172- | - | - 173l | l | l 174l | l | l 175- | - | - 176l | l | l 177- | - | - 178l | l | l 179- | - | - 180l | l | l. 181Subcommand:Arguments:Description 182get:[module]:Gets details about the motors 183set:module:Set the power value for a motor 184:A or B: 185:value from -127 to 127: 186invert:module:Inverts the power value for a motor 187:A or B: 188bridge:module:Bridge motors A and B on a module together 189enable::Enable the driver, apply the directed power to the motors 190disable::Disable the driver, remove all power 191.TE 192.It read_register Ar module Ar register Ar [register_end] 193Read the registers from a module starting with register and optionally 194ending with register_end. The values for register and register_end are 195in the range from 0 to 126 in either decimal or hex or they may be a 196named register. 197.It write_register Ar module Ar register Ar value 198Write a value to a register on a module. The register values are from 1990 to 126 in either decimal or hex or may be a named register name. The 200value that can be written to a register is 0 to 255 either in decimal or 201hex. 202.It restart 203Issue a restart directive to the SCMD. 204.It re-enumerate 205Issue a re-enumeration command to the SCMD. This will cause the master module 206to search the expansion bus I2C chain for additional modules. 207.It update_rate Ar get|set|force Ar rate(set) 208Set the update rate in which the master module updates the remote modules. If 209rate is set to 0 then updates will only happen when force is done. 210.It expansion_bus Ar get|set Ar 50kHz|100kHz|400kHz(set) 211Set the speed of the expandsion I2C bus. 212.It lock Ar get|lock|unlock Ar local_user|local_master|global_user|global_master 213View lock or unlock one of the locks on the SCMD device. Global locks are 214sent to any attached SCMD device on the expansion bus, and local locks apply 215only to the master module. 216.It spi_read_one 217This command is usable only in SPI userland mode and performs a single receive 218in the hopes of unsticking the SCMD device. 219.El 220.Sh EXAMPLES 221.Pp 222.Dl "scmdctl /dev/dtyU0 identify" 223.Pp 224Perform a identify command against the serial device /dev/dtyU0 and return 225the results. 226.Pp 227.Dl "scmdctl /dev/spi0 motor get 0" 228.Pp 229Get the status of the motors on module 0 by accessing the SCMD device using 230userland SPI. 231.Pp 232.Dl "scmdctl /dev/scmd0 motor set 1 B 127" 233.Dl "scmdctl /dev/scmd0 motor invert 1 B" 234.Pp 235Set the power value of the B motor on module 1 to 127 and then invert the power. 236Note that the values returned by a get against module 1 will still show the 237positive value 127, but will indicate that the motor power is inverted. 238.Pp 239.Dl "scmdctl /dev/scmd0 read_register 0 0x00 4" 240.Dl "scmdctl /dev/scmd0 read_register 0 FID CONFIG_BITS" 241.Pp 242Read the first four registers on the master SCMD module using the kernel 243.Xr scmd 4 244device. Both of those two examples return the same information. 245.Sh SEE ALSO 246.Xr iic 4 , 247.Xr spi 4 , 248.Xr scmdi2c 4 , 249.Xr scmdspi 4 , 250.Sh HISTORY 251The 252.Nm 253utility first appeared in 254.Nx 10.0 . 255.Sh AUTHORS 256.An -nosplit 257The 258.Nm 259utility was written by 260.An Brad Spencer Aq Mt brad@anduin.eldar.org . 261.Sh BUGS 262When accessing the SCMD devices using tty uart access, it is not really 263possible to deal with line noise and there is no safety checks built into 264the device to help with this. It is entirely possible that the 265.Xr scmdctl 1 266command can hang in this mode. It is also possible and likely that the 267.Xr scmdctl 1 268command will hang after a restart is performed in this mode. 269.Pp 270Performing a read in SPI mode, either in the kernel or in userland, is a 271little odd with the SCMD device. There is a requirement that a dummy or 272null read be performed and if this does not work as expected further reads 273will not work. The spi_read_one command is an attempt to unstick 274a stuck SCMD device. 275.Pp 276If the SPI or I2C pins are not set up when the kernel device driver attaches 277it will not be able to display information about the device, but it will also 278not be able to ask the device how many modules exist and will more or less 279assume that only the master node exists. If further set up is required after 280the device attaches, a re-enumeration should be performed before any actions 281are done to the motors. 282.Pp 283No attempt has been made with 284.Xr scmdctl 1 285to make the failsafe functions of the SCMD device available in any convient manor. 286