iP Solu­tions has cre­ated a Ser­ial Periph­eral Inter­face (SPI) command-line util­ity for the Rasp­berry Pi (www.raspberrypi.org) plat­form.  The util­ity, spincl, is licensed under Open Source GNU GPLv3 and is being offered by iP Solu­tions as a free down­load with source included.

Although a C library exists for the Broad­com bcm2835 with an SPI Appli­ca­tion Pro­gram­ming Inter­face (API) among other things, there are rea­sons to have a command-line util­ity, which can be invoked from a shell com­mand line or from within a script.  A command-line util­ity allows easy test­ing and debug­ging of SPI slave devices with­out hav­ing to develop a C exe­cutable.  Addi­tion­ally, it pro­vides a sim­ple way for bash and python scripts to access the SPI mas­ter of the BCM2835 on Rasp­berry Pi. Although the raspian dis­tri­b­u­tion pro­vides GPIO libraries with the included python instal­la­tion it doesn’t include an SPI library. spincl, on the other hand, can be invoked from a python (or bash) script.  

Descrip­tion

spincl is a command-line util­ity for exe­cut­ing SPI com­mands with the Broad­com bcm2835 from a shell com­mand line (or script).  The util­ity is based on the bcm2835 C library devel­oped by Mike McCauley of Open Sys­tem Con­sul­tants, http://www.open.com.au/mikem/bcm2835.  It was built with ver­sion 1.17 of the bcm2835 library and tested on a Rasp­berry Pi single-board com­puter model B with an iP Solu­tions designed I/O board, which con­tains SPI acces­si­ble ADC and dig­i­tal I/O expansion.

Invok­ing spincl results in a full-duplex SPI trans­fer.  Options include the the SPI clock fre­quency, SPI Mode, chip select des­ig­na­tion, and chip select polar­ity.  Invok­ing spincl requires root priv­i­lege.  If no command-line argu­ments are included or if there are any command-line argu­ment errors, a “usage state­ment” will be printed on std­out sim­i­lar to the Usage doc­u­men­ta­tion below.

Usage

spincl [options] len [xmit bytes]

Invok­ing spincl results in a full-duplex SPI trans­fer of a spec­i­fied num­ber of bytes.  Addi­tion­ally, it can be used to set the appro­pri­ate  GPIO pins to their respec­tive SPI con­fig­u­ra­tions or return them  to GPIO input con­fig­u­ra­tion.  Options include the SPI clock fre­quency,  SPI Mode, chip select des­ig­na­tion, chip select polar­ity and an  ini­tial­iza­tion option (spi_begin and spi_end).

spincl must be invoked  with root priv­i­leges.  How­ever, as of ver­sion 1.3.0, although the make install tar­get included in the Make­file installs spincl with a root owner, it also sets the suid bit so that users other than root may invoke spincl with­out a sudo pre­fix.

The fol­low­ing are the options, which must be a sin­gle let­ter  pre­ceded by a ‘-’ and fol­lowed by another character:

• –ix where x is the SPI init option, b[egin] or e[nd].  The begin option must be exe­cuted before any trans­fer can hap­pen.   It may option­ally be included with a trans­fer.   The end option will return the SPI pins to GPIO inputs.   It may also option­ally be included with a transfer.
• –mx where x is the SPI mode, 0, 1, 2, or 3
• –cx where x is the expo­nent of 2 of the clock divider.   Allowed val­ues  are 0 through 15.  Valid clock divider val­ues are pow­ers of 2.  Cor­re­spond­ing fre­quen­cies are spec­i­fied in bcm2835.h.
• –sx where x is 0 (CS0), 1 (CS1), 2 (CS1&CS2), or 3 (None)
• –px where x is chip select polar­ity, 0(LOW) or 1(HIGH)

len: The num­ber of bytes to be trans­mit­ted and received (full duplex).

xmit bytes:  The bytes to be trans­mit­ted if spec­i­fied.  If none are spec­i­fied, 0s will be trans­mit­ted, which may be the case when only the received data is relevant.

Exam­ples

Use spincl to just intial­ize the SPI pins: spincl –ib

Use spincl to intial­ize the SPI pins and read three bytes (note xmit bytes are not spec­i­fied).  Mode is 2, clock fre­quency is 15.625Mhz (see bcm2835.h), chip select is 0, and polar­ity is active low:  spincl –ib –m2 –c4 –s0 –p0 3

Use spincl to trans­mit 2 bytes (spec­i­fied) and read back 2 bytes, which may or may not be rel­e­vant.  Mode is 1, clock fre­quency is 7.8125MHz, chip select is 1, and polar­ity is active high.  Note that no ini­tial­iza­tion has been spec­i­fied so SPI pins must have been pre­vi­ously ini­tial­ized:  spincl –m1 –c5 –s1 –p1 2 0x5c 0x13

Use spincl to read two byte with mode 3, clock fre­quency of 15.625Mhz, and no chip select (done by user some other way).  When the SPI tran­fer has been com­pleted, the SPI pins will be returned to GPIO inputs:  spincl –ie –m3 –c4 –s3 2

Use spincl to just return the SPI pins to GPIO inputs:  spincl –ie

Build

Of course the spincl exe­cutable will work as is.  How­ever, if you want to make edits to the source, a Make­file is included to rebuild the exe­cutable.  The Make­file assumes that the bcm2835 library has been installed.  In other words, bcm2835.h is in /usr/local/include and libbcm2835.a is in /usr/local/lib.  To “make” the exe­cutable, type make at the command-line prompt from the spincl direc­tory.  Again, the ver­sion of the  bcm2835 library that was used to build the exe­cutable included in the down­load is 1.17.  You may wish to try build­ing spincl with the most cur­rent ver­sion.  An exam­ple “install” tar­get is included in the Make­file, which installs spincl in /opt/bin with root own­er­ship and group with appro­pri­ate priv­i­leges, includ­ing set­ting the suid bit.  Edit them as required for your application.

Get Free Download

Click here to down­load lat­est update of spincl.tar.gz     Down­load

Place the tar­ball file in the desired direc­tory and then execute:

• tar –xzvf spincl.tar.gz (spincl_1_3_1.tar.gz as of 7/31/13)

to get the expanded source directory.

Updates

• Ver­sion 1.3.0, 5/19/24:
  • Bug Fix:  A bug in the way the num­ber of trasmit bytes was cal­cu­lated was fixed.  Pre­vi­ously, if the total byte length of the trans­fer was greater than the num­ber of spec­i­fied xmit bytes then an attempt to access command-line argu­ments beyond the num­ber avail­able would occur, which causes a seg­men­ta­tion fault.
  • suid bit is now set in the install tar­get of Makefile.
• Ver­sion 1.3.1, 6/25/13:
  • This ver­sion was built with the bcm2835-1.25 library.  All pre­vi­ous ver­sions were built with bcm2835-17.
  • This ver­sion was tested on 2013-02-09 raspian wheezy. The 2012-10-28 raspian wheezy was used for all pre­vi­ous versions.

iP Solu­tions in no way war­rants or guar­an­tees cor­rect­ness of the down­loaded code or that it’s bug-free.