xref: /netbsd-src/usr.bin/scmdctl/scmdctl.1 (revision bf53d4416703565e0d45b6919cbfae62d21a4872)
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