Module: Beaglebone::SPI

Defined in:
lib/beaglebone/spi.rb

Overview

SPI

Procedural methods for SPI control

Summary

#setup is called to initialize an SPI device

Constant Summary collapse

IOC_NONE =

some ioctl defines

0
IOC_WRITE = 
1
IOC_READ = 
2
IOC_NRBITS = 
8
IOC_TYPEBITS = 
8
IOC_SIZEBITS = 
14
IOC_DIRBITS = 
2
IOC_NRSHIFT = 
0
IOC_TYPESHIFT = 
IOC_NRSHIFT+IOC_NRBITS
IOC_SIZESHIFT = 
IOC_TYPESHIFT+IOC_TYPEBITS
IOC_DIRSHIFT = 
IOC_SIZESHIFT+IOC_SIZEBITS
SPI_CPHA =

spi defines

0x01
SPI_CPOL = 
0x02
SPI_MODE_0 = 
(0|0)
SPI_MODE_1 = 
(0|SPI_CPHA)
SPI_MODE_2 = 
(SPI_CPOL|0)
SPI_MODE_3 = 
(SPI_CPOL|SPI_CPHA)
SPI_MODES = 
{
  :SPI_MODE_0 => SPI_MODE_0,
  :SPI_MODE_1 => SPI_MODE_1,
  :SPI_MODE_2 => SPI_MODE_2,
  :SPI_MODE_3 => SPI_MODE_3,
}
SPI_CS_HIGH = 
0x04
SPI_LSB_FIRST = 
0x08
SPI_3WIRE = 
0x10
SPI_LOOP = 
0x20
SPI_NO_CS = 
0x40
SPI_READY = 
0x80
SPI_IOC_MAGIC = 
'k'.ord
SPI_IOC_RD_MODE =

ior(SPI_IOC_MAGIC, 1, 1)

2147576577
SPI_IOC_WR_MODE =

iow(SPI_IOC_MAGIC, 1, 1)

1073834753
SPI_IOC_RD_LSB_FIRST =

ior(SPI_IOC_MAGIC, 2, 1)

2147576578
SPI_IOC_WR_LSB_FIRST =

iow(SPI_IOC_MAGIC, 2, 1)

1073834754
SPI_IOC_RD_BITS_PER_WORD =

ior(SPI_IOC_MAGIC, 3, 1)

2147576579
SPI_IOC_WR_BITS_PER_WORD =

iow(SPI_IOC_MAGIC, 3, 1)

1073834755
SPI_IOC_RD_MAX_SPEED_HZ =

ior(SPI_IOC_MAGIC, 4, 4)

2147773188
SPI_IOC_WR_MAX_SPEED_HZ =

iow(SPI_IOC_MAGIC, 4, 4)

1074031364
SPI_IOC_MESSAGE_1 = 
1075866368
SPI_IOC_TRANSFER_STRUCT_SIZE = 
32

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.spimutex ⇒ Object

Returns the value of attribute spimutex.



70
71
72
 
# File 'lib/beaglebone/spi.rb', line 70

def spimutex
  @spimutex
end

.spistatus ⇒ Object

Returns the value of attribute spistatus.



70
71
72
 
# File 'lib/beaglebone/spi.rb', line 70

def spistatus
  @spistatus
end

Class Method Details

.cleanup ⇒ Object

Disable all active SPI devices



282
283
284
285
 
# File 'lib/beaglebone/spi.rb', line 282

def cleanup
  #reset all spis we've used and unload the device tree
  spistatus.clone.keys.each { |spi| disable(spi)}
end

.disable(spi) ⇒ Object

Note:

device trees cannot be unloaded at this time without kernel panic.

Disable the specified SPI device

Parameters:

  • spi —

    should be a symbol representing the SPI device



266
267
268
269
270
271
272
273
274
275
276
277
278
279
 
# File 'lib/beaglebone/spi.rb', line 266

def disable(spi)
  check_spi_valid(spi)
  check_spi_enabled(spi)

  SPIS[spi][:pins].each do |pin|
    disable_spi_pin(pin)
  end

  delete_spi_status(spi)

  #removing spi tree causes a crash... can't really disable.
  #Beaglebone::device_tree_unload("#{SPIS[spi][:devicetree]}") if SPIS[spi][:devicetree]

end

.file(spi) ⇒ Object

Return the file descriptor to the open SPI device

Parameters:

  • spi —

    should be a symbol representing the SPI device



184
185
186
187
 
# File 'lib/beaglebone/spi.rb', line 184

def file(spi)
  check_spi_enabled(spi)
  get_spi_status(spi, :fd_spi)
end

.set_bpw(spi, bpw) ⇒ Object

Set the bits per word of the specified SPI device

Parameters:

  • spi —

    should be a symbol representing the SPI device

  • bpw —

    should specify the bits per word

Raises:

  • (ArgumentError) 


241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
 
# File 'lib/beaglebone/spi.rb', line 241

def set_bpw(spi, bpw)
  bpw = bpw.to_i
  raise ArgumentError, "BPW (#{bpw.to_s}) must be a positive integer" unless bpw > 0

  check_spi_enabled(spi)
  spi_fd = get_spi_status(spi, :fd_spi)

  spi_fd.ioctl(SPI_IOC_WR_BITS_PER_WORD, [bpw].pack('C'))

  # deal with old versions of ruby that can't handle large number IOCTL
  # https://bugs.ruby-lang.org/issues/6127
  begin
    spi_fd.ioctl(SPI_IOC_RD_BITS_PER_WORD, [bpw].pack('C'))
  rescue
    puts 'Warning, old Ruby detected, cannot set SPI read bits per word'
  end

  set_spi_status(spi, :bpw, bpw)
end

.set_mode(spi, mode) ⇒ Object

Set the communication speed of the specified SPI device

Parameters:

  • spi —

    should be a symbol representing the SPI device

  • mode —

    should be a valid SPI mode, e.g. :SPI_MODE_0 through 3

Raises:

  • (ArgumentError) 


217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/beaglebone/spi.rb', line 217

def set_mode(spi, mode)
  check_spi_enabled(spi)

  #if mode is a symbol, translate it to the appropriate value
  mode = SPI_MODES[mode] if mode.class == Symbol && SPI_MODES[mode]

  raise ArgumentError, "Mode (#{mode.to_s}) is unknown" unless SPI_MODES.values.include?(mode)
  spi_fd = get_spi_status(spi, :fd_spi)

  # deal with old versions of ruby that can't handle large number IOCTL
  # https://bugs.ruby-lang.org/issues/6127
  begin
    spi_fd.ioctl(SPI_IOC_WR_MODE, [mode].pack('C'))
    spi_fd.ioctl(SPI_IOC_RD_MODE, [mode].pack('C'))
  rescue
    puts 'Warning, old Ruby detected, cannot set SPI mode'
  end

end

.set_speed(spi, speed) ⇒ Object

Set the communication speed of the specified SPI device

Parameters:

  • spi —

    should be a symbol representing the SPI device

  • speed —

    communication speed

Raises:

  • (ArgumentError) 


193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/beaglebone/spi.rb', line 193

def set_speed(spi, speed)
  speed = speed.to_i
  raise ArgumentError, "Speed (#{speed.to_s}) must be a positive integer" unless speed > 0

  check_spi_enabled(spi)
  spi_fd = get_spi_status(spi, :fd_spi)

  spi_fd.ioctl(SPI_IOC_WR_MAX_SPEED_HZ, [speed].pack('L'))

  # deal with old versions of ruby that can't handle large number IOCTL
  # https://bugs.ruby-lang.org/issues/6127
  begin
    spi_fd.ioctl(SPI_IOC_RD_MAX_SPEED_HZ, [speed].pack('L'))
  rescue
    puts 'Warning, old Ruby detected, cannot set SPI max read speed'
  end

  set_spi_status(spi, :speed, speed)
end

.setup(spi, mode = nil, speed = 1000000, bpw = 8) ⇒ Object

Initialize an SPI device

Examples:

SPI.setup(:SPI0, SPI_MODE_0)

Parameters:

  • spi —

    should be a symbol representing the SPI device

  • mode (defaults to: nil) —

    optional, default 0, specifies the SPI mode :SPI_MODE_0 through 3

  • speed (defaults to: 1000000) —

    optional, specifies the SPI communication speed

  • bpw (defaults to: 8) —

    optional, specifies the bits per word



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/beaglebone/spi.rb', line 81

def setup(spi, mode=nil, speed=1000000, bpw=8)
  check_spi_valid(spi)

  #make sure spi not already enabled
  return if get_spi_status(spi)

  mode = mode || SPI_MODE_0

  spiinfo = SPIS[spi]

  #ensure dtb is loaded
  Beaglebone::device_tree_load("#{spiinfo[:devicetree]}") if spiinfo[:devicetree]

  #open the spi device.
  spi_fd = File.open("#{spiinfo[:dev]}#{SPIS[:counter]}.0", 'r+')

  set_spi_status(spi, :fd_spi, spi_fd)
  set_spi_status(spi, :mutex, Mutex.new)

  set_mode(spi, mode)
  set_bpw(spi, bpw)
  set_speed(spi, speed)

  SPIS[:counter] += 1

  spiinfo[:pins].each do |pin|
    Beaglebone::set_pin_status(pin, :spi, spiinfo[:id])
    Beaglebone::set_pin_status(pin, :type, :spi)
    Beaglebone::set_pin_status(pin, :fd_spi, spi_fd)
  end

end

.xfer(spi, tx_data, readbytes = 0, speed = nil, delay = nil, bpw = nil) ⇒ Object

Transfer data to and from the SPI device

Examples:

# communicate with MCP3008
# byte 1: start bit
# byte 2: single(1)/diff(0),3 bites for channel, null pad
# byte 3: don't care
SPI.setup(:SPI0, SPI_MODE_0)
raw = SPI.xfer(:SPI0, [ 0b00000001, 0b10000000, 0].pack("C*"))
data = raw.unpack("C*")
val = ((data[1] & 0b00000011) << 8 ) | data[2]

Parameters:

  • spi —

    should be a symbol representing the SPI device

  • tx_data —

    data to transmit

  • readbytes (defaults to: 0) —

    bytes to read, otherwise it sizeof tx_data is used

  • speed (defaults to: nil) —

    optional, speed to xfer at

  • delay (defaults to: nil) —

    optional delay

  • bpw (defaults to: nil) —

    optional bits per word

Returns:

  • String data read from SPI device



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/beaglebone/spi.rb', line 134

def xfer(spi, tx_data, readbytes=0, speed=nil, delay=nil, bpw=nil)
  check_spi_enabled(spi)

  speed = speed || get_spi_status(spi, :speed)
  delay = delay || 0
  bpw   = bpw || get_spi_status(spi, :bpw)

  if tx_data.size > readbytes
    readbytes = tx_data.size
  end

  rx_data = ' ' * readbytes

  lock_spi(spi) do
    spi_fd = get_spi_status(spi, :fd_spi)

    ### SPI IOC transfer structure
    # __u64       tx_buf;
    # __u64       rx_buf;
    #
    # __u32       len;
    # __u32       speed_hz;
    #
    # __u16       delay_usecs;
    # __u8        bits_per_word;
    # __u8        cs_change;
    # __u32       pad;
    ###

    msg = [ tx_data, 0,
            rx_data, 0,
            readbytes,
            speed,
            delay,
            bpw,
            0,
            0].pack('pLpLLLSCCL')

    #ioctl call to begin data transfer
    spi_fd.ioctl(SPI_IOC_MESSAGE_1, msg)
    #speedup with defined int
    #spi_fd.ioctl(spi_ioc_message(1), msg)

  end
  rx_data
end