BlackLib::BlackSPI Class Reference

Interacts with end user, to use SPI. More...

#include <BlackSPI.h>

Inheritance diagram for BlackLib::BlackSPI:

Public Types

enum  flags {
  dtErr = 1,
  openErr = 2,
  closeErr = 3,
  portPathErr = 4,
  transferErr = 5,
  modeErr = 6,
  speedErr = 7,
  bitSizeErr = 8
}
 

Public Member Functions

 BlackSPI (spiName spi)
 Constructor of BlackSPI class. More...
 
 BlackSPI (spiName spi, BlackSpiProperties spiProperties)
 Constructor of BlackSPI class. More...
 
 BlackSPI (spiName spi, uint8_t spiBitsPerWord, uint8_t spiMode, uint32_t spiSpeed)
 Constructor of BlackSPI class. More...
 
virtual ~BlackSPI ()
 Destructor of BlackSPI class. More...
 
bool open (uint openMode)
 Opens TTY file of spi. More...
 
bool close ()
 Closes TTY file of spi. More...
 
uint8_t transfer (uint8_t writeByte, uint16_t wait_us=10)
 Transfers byte to/from slave. More...
 
bool transfer (uint8_t *writeBuffer, uint8_t *readBuffer, size_t bufferSize, uint16_t wait_us=10)
 Transfers datas to/from slave. More...
 
bool setBitsPerWord (uint8_t newBitSize)
 Changes word size of spi. More...
 
bool setMaximumSpeed (uint32_t newSpeed)
 Changes maximum speed of spi. More...
 
bool setMode (uint8_t newMode)
 Changes mode of spi. More...
 
bool setProperties (BlackSpiProperties &newProperties)
 Changes properties of spi. More...
 
string getPortName ()
 Exports spi's port path. More...
 
uint8_t getBitsPerWord ()
 Exports word size of spi. More...
 
uint32_t getMaximumSpeed ()
 Exports maximum speed of spi. More...
 
uint8_t getMode ()
 Exports mode of spi. More...
 
BlackSpiProperties getProperties ()
 Exports properties of spi. More...
 
bool isOpen ()
 Checks spi's tty file's open state. More...
 
bool isClose ()
 Checks spi's tty file's close state. More...
 
bool fail ()
 Is used for general debugging. More...
 
bool fail (BlackSPI::flags f)
 Is used for specific debugging. More...
 

Private Member Functions

bool loadDeviceTree ()
 Loads SPI overlay to device tree. More...
 
bool findPortPath ()
 Finds SPI's port path and bus number. More...
 
- Private Member Functions inherited from BlackLib::BlackCore
 BlackCore ()
 Constructor of BlackCore class. More...
 
virtual ~BlackCore ()
 Destructor of BlackCore class. More...
 
std::string searchDirectoryOcp (BlackCore::ocpSearch searchThis)
 Searches ocp directory to find specified file/directory. More...
 
errorCoregetErrorsFromCore ()
 Exports errorCore struct to derived class. More...
 
std::string getCapeMgrName ()
 Exports capemgr name to derived class. More...
 
std::string getOcpName ()
 Exports ocp name to derived class. More...
 
std::string getSlotsFilePath ()
 Exports slots file path to derived class. More...
 

Private Attributes

BlackSpiProperties constructorProperties
 is used to hold the user specified properties of spi More...
 
BlackSpiProperties defaultProperties
 is used to hold the default properties of spi More...
 
BlackSpiProperties currentProperties
 is used to hold the current properties of spi More...
 
errorSPIspiErrors
 is used to hold the errors of BlackSPI class More...
 
std::string spiPortPath
 is used to hold the spi's tty port path More...
 
std::string dtSpiFilename
 is used to hold the spi's device tree overlay name More...
 
int spiFD
 is used to hold the spi's tty file's file descriptor More...
 
int spiBusNumber
 is used to hold the spi's bus number More...
 
int spiChipNumber
 is used to hold the spi's chip number More...
 
bool isCurrentEqDefault
 is used to hold the properties of spi is equal to default properties More...
 
bool isOpenFlag
 is used to hold the spi's tty file's state More...
 

Additional Inherited Members

- Private Types inherited from BlackLib::BlackCore
enum  ocpSearch {
  ADC_helper = 0,
  PWM_P8_13 = 1,
  PWM_P8_19 = 2,
  PWM_P9_14 = 3,
  PWM_P9_16 = 4,
  PWM_P9_21 = 5,
  PWM_P9_22 = 6,
  PWM_P9_42 = 7,
  SPI0 = 8,
  SPI1 = 9
}
 

Detailed Description

Interacts with end user, to use SPI.

This class is end node to use spi. End users interact with spi from this class. It includes public functions to set and get properties of spi's and to transfer datas. Spi has not capable of only read operation. For reading something from spi, user's must send dummy data.

Warning
Users have to execute setup script before use spi. This is required for compiling and setting device tree overlays about spi.
Spi speed can be 24000000 Hz(24 MHz) maximum.
Example
EXAMPLE PROJECT FILE TREE:

   mySpiProject
   |-> src
       |-> BlackLib
           |-> BlackDirectory
               |-> BlackDirectory.cpp
               |-> BlackDirectory.h
           |-> BlackThread
               |-> BlackThread.cpp
               |-> BlackThread.h
           |-> BlackMutex
               |-> BlackMutex.cpp
               |-> BlackMutex.h
           |-> BlackTime
               |-> BlackTime.cpp
               |-> BlackTime.h
           |-> BlackADC
               |-> BlackADC.cpp
               |-> BlackADC.h
           |-> BlackGPIO
               |-> BlackGPIO.cpp
               |-> BlackGPIO.h
           |-> BlackI2C
               |-> BlackI2C.cpp
               |-> BlackI2C.h
           |-> BlackPWM
               |-> BlackPWM.cpp
               |-> BlackPWM.h
           |-> BlackSPI
               |-> BlackSPI.cpp
               |-> BlackSPI.h
           |-> BlackUART
               |-> BlackUART.cpp
               |-> BlackUART.h
           |-> BlackCore.cpp
           |-> BlackCore.h
           |-> BlackDef.h
           |-> BlackErr.h
           |-> BlackLib.h
       |-> mySpiProject.cpp


If BlackLib source files are located in your project like above example project file tree, you have to include BlackSPI.h or another source files with adding this line to your project file (mySpiProject.cpp at the example):
#include "BlackLib/BlackSPI/BlackSPI.h"


If BlackLib source files are located at same level with your project file (mySpiProject.cpp at the example), you have to include BlackSPI.h or another source files with adding this line to your project file:

// Filename: mySpiProject.cpp
// Author: Yiğit Yüce - ygtyce@gmail.com
#include <iostream>
#include "BlackLib/BlackSPI/BlackSPI.h"
int main()
{
uint8_t writeArr[4] = { 0x55, 0xaa, 0xf0, 0x0c };
uint8_t readArr[4];
mySpi.transfer(writeArr, readArr, sizeof(writeArr), 100);
return 0;
}


You can use "using namespace BlackLib" also. You can get rid of writing "BlackLib::", with using this method.
// Filename: mySpiProject.cpp
// Author: Yiğit Yüce - ygtyce@gmail.com
#include <iostream>
#include "BlackLib/BlackSPI/BlackSPI.h"
using namespace BlackLib;
int main()
{
BlackSPI mySpi(SPI0_0, 8, SpiDefault, 2400000);
mySpi.open( ReadWrite|NonBlock );
uint8_t writeArr[4] = { 0x55, 0xaa, 0xf0, 0x0c };
uint8_t readArr[4];
mySpi.transfer(writeArr, readArr, sizeof(writeArr), 100);
return 0;
}

Member Enumeration Documentation

This enum is used to define SPI debugging flags.

Enumerator
dtErr 

enumeration for errorSPI::dtError status

openErr 

enumeration for errorSPI::openError status

closeErr 

enumeration for errorSPI::closeError status

portPathErr 

enumeration for errorSPI::portPathError status

transferErr 

enumeration for errorSPI::transferError status

modeErr 

enumeration for errorSPI::modeError status

speedErr 

enumeration for errorSPI::speedError status

bitSizeErr 

enumeration for errorSPI::bitSizeError status

Constructor & Destructor Documentation

BlackLib::BlackSPI::BlackSPI ( spiName  spi)

Constructor of BlackSPI class.

This function initializes errorSPI struct, sets local variables. Then calls device tree loading function and port path finding function. Objects which are initialized from BlackSPI class with this constructor, uses default line properties.

Parameters
[in]spiname of spi (enum),(SPIx_y)
Example
See also
loadDeviceTree()
findPortPath()
spiName
BlackLib::BlackSPI::BlackSPI ( spiName  spi,
BlackSpiProperties  spiProperties 
)

Constructor of BlackSPI class.

This function initializes errorSPI struct, sets value of constructorProperties struct and local variables. Then calls device tree loading function and port path finding function.

Parameters
[in]spiname of spi (enum),(SPIx_y)
[in]spiPropertiesimport properties from outside
Example
See also
loadDeviceTree()
findPortPath()
spiName
BlackSpiProperties
BlackLib::BlackSPI::BlackSPI ( spiName  spi,
uint8_t  spiBitsPerWord,
uint8_t  spiMode,
uint32_t  spiSpeed 
)

Constructor of BlackSPI class.

This function initializes errorSPI struct, sets value of constructorProperties struct and local variables. Then calls device tree loading function and port path finding function.

Parameters
[in]spiname of spi (enum),(SPIx_y)
[in]spiBitsPerWordword size of spi
[in]spiModemode of spi
[in]spiSpeedtransfer speed of spi
Example
See also
loadDeviceTree()
findPortPath()
spiName
BlackSpiProperties::spiBitsPerWord
BlackSpiProperties::spiMode
BlackSpiProperties::spiSpeed
BlackLib::BlackSPI::~BlackSPI ( )
virtual

Destructor of BlackSPI class.

This function closes TTY file and deletes errorSPI struct pointer.

Member Function Documentation

bool BlackLib::BlackSPI::close ( )

Closes TTY file of spi.

This function closes spi's TTY file and changes isOpenFlag's value.

Returns
True if tty file closing successful, else false.
Example
See also
BlackSPI::isOpenFlag
bool BlackLib::BlackSPI::fail ( )

Is used for general debugging.

Returns
True if any error occured, else false.
Example
if( mySpi.fail() )
{
std::cout << "ERROR OCCURED" << std::endl;
}
else
{
std::cout << "EVERYTHING IS OK" << std::endl;
}
// Possible Output:
// EVERYTHING IS OK
See also
errorSPI
bool BlackLib::BlackSPI::fail ( BlackSPI::flags  f)

Is used for specific debugging.

You can use this function, after call BlackSPI member functions in your code. The input parameter is used for finding out status of selected error.

Parameters
[in]fspecific error type (enum)
Returns
Value of selected error.
Example
{
std::cout << "BlackSPI INITIALIZATION FAILED" << std::endl;
}
else
{
std::cout << "BlackSPI INITIALIZATION IS OK" << std::endl;
}
if( mySpi.fail(BlackLib::BlackSPI::openErr) )
{
std::cout << "OPENNING ERROR OCCURED" << std::endl;
}
else
{
std::cout << "OPENNING IS OK" << std::endl;
}
uint8_t sendBytes[4] = { 0x87, 0x41, 0xF1, 0x5A };
uint8_t recvBytes[4];
mySpi.transfer(sendBytes, recvBytes, sizeof(sendBytes), 100);
{
if( mySpi.fail(BlackLib::BlackSPI::openErr) )
{
std::cout << "TRANSFER ERROR OCCURED BECAUSE SPI TTY IS NOT OPEN" << std::endl;
}
else
{
std::cout << "TRANSFER ERROR OCCURED" << std::endl;
}
}
else
{
std::cout << "TRANSFER IS OK" << std::endl;
}
// Possible Output:
// BlackSPI INITIALIZATION IS OK
// OPENNING IS OK
// TRANSFER IS OK
See also
errorSPI
bool BlackLib::BlackSPI::findPortPath ( )
private

Finds SPI's port path and bus number.

The spi's TTY file name which located at "/dev/" directory, is differed to device tree overlay loading order. For example if users want to use both of spi bus and loads spi1 and then spi0 overlay to device tree, Beaglebone generates TTY file "spidev1.x" for spi1 and "spidev2.x" for spi0. But if users loads first spi0 and then spi1 overlay to device tree, this time Beaglebone generates TTY file "spidev1.x" for spi0 and "spidev2.x" for spi1. For this reason which file associated with which spi, must find. This function does these operations exactly.

Returns
True if successful, else false.
uint8_t BlackLib::BlackSPI::getBitsPerWord ( )

Exports word size of spi.

Returns
bits per word size of spi
Example
Example usage is shown in BlackSPI::setBitsPerWord() function's example.
See also
BlackSpiProperties::spiBitsPerWord
uint32_t BlackLib::BlackSPI::getMaximumSpeed ( )

Exports maximum speed of spi.

Returns
maximum speed of spi
Example
Example usage is shown in BlackSPI::setMaximumSpeed() function's example.
See also
BlackSpiProperties::spiSpeed
uint8_t BlackLib::BlackSPI::getMode ( )

Exports mode of spi.

Returns
mode of spi
Example
Example usage is shown in BlackSPI::setMode() function's example.
See also
BlackSpiProperties::spiMode
BlackLib::spiMode
std::string BlackLib::BlackSPI::getPortName ( )

Exports spi's port path.

Returns
spi's port path as string.
Example
std::cout << "Port path: " << mySpi.getPortName();
// Possible Output:
// Port path: /dev/spidev1.0
See also
spiPortPath
BlackSpiProperties BlackLib::BlackSPI::getProperties ( )

Exports properties of spi.

This function gets properties of spi. These properties are composed of word size, speed and mode.

Returns
BlackSPI::currentProperties struct with updated values.
Example
Example usage is shown in BlackSPI::setProperties() function's example.
See also
BlackSpiProperties
bool BlackLib::BlackSPI::isClose ( )

Checks spi's tty file's close state.

Returns
true if tty file is close, else false.
Example
std::cout << "Is close?: " << std::boolalpha << mySpi.isClose() << std::endl;
std::cout << "Is close?: " << std::boolalpha << mySpi.isClose();
// Possible Output:
// Is close?: true
// Is close?: false
See also
BlackSPI::isOpenFlag
bool BlackLib::BlackSPI::isOpen ( )

Checks spi's tty file's open state.

Returns
true if tty file is open, else false.
Example
std::cout << "Is open?: " << std::boolalpha << mySpi.isOpen() << std::endl;
std::cout << "Is open?: " << std::boolalpha << mySpi.isOpen();
// Possible Output:
// Is open?: false
// Is open?: true
See also
BlackSPI::isOpenFlag
bool BlackLib::BlackSPI::loadDeviceTree ( )
privatevirtual

Loads SPI overlay to device tree.

This function loads BlackSPI::dtSpiFilename overlay to device tree. This file name changes with spiName constructor parameter. This overlay performs pinmuxing and generates device driver.

Warning
BlackSPI class uses custom device tree overlays. Users must install these overlays firstly by executing setup script.
Returns
True if successful, else false.

Implements BlackLib::BlackCore.

bool BlackLib::BlackSPI::open ( uint  openMode)

Opens TTY file of spi.

This function opens spi's TTY file with selected open mode, gets default properties of SPI and saves this properties to BlackSPI::defaultProperties struct. Then sets properties which are specified at class initialization stage. Users can send "or"ed BlackLib::openMode enums as parameter to this function.

Warning
After initialization of BlackSPI class, this function must call. Otherwise users could not use any of data transfering functions.
Parameters
[in]openModefile opening mode
Returns
True if tty file opening successful, else false.
Example
See also
openMode
bool BlackLib::BlackSPI::setBitsPerWord ( uint8_t  newBitSize)

Changes word size of spi.

This function changes bits per word size of spi on fly.

Parameters
[in]newBitSizenew word size
Returns
true if changing operation is successful, else false.
Example
std::cout << "Current bits per word size: " << (int)mySpi.getBitsPerWord() << std::endl;
mySpi.setBitsPerWord(10);
std::cout << "Current bits per word size: " << (int)mySpi.getBitsPerWord();
// Possible Output:
// Current bits per word size: 8
// Current bits per word size: 10
See also
BlackSpiProperties::spiBitsPerWord
bool BlackLib::BlackSPI::setMaximumSpeed ( uint32_t  newSpeed)

Changes maximum speed of spi.

This function changes maximum speed of spi on fly.

Parameters
[in]newSpeednew speed value
Returns
true if changing operation is successful, else false.
Example
std::cout << "Current speed: " << mySpi.getMaximumSpeed() << " Hz\n";
mySpi.setMaximumSpeed(18000000);
std::cout << "Current speed: " << mySpi.getMaximumSpeed() << " Hz";
// Possible Output:
// Current speed: 2400000 Hz
// Current speed: 18000000 Hz
See also
BlackSpiProperties::spiSpeed
bool BlackLib::BlackSPI::setMode ( uint8_t  newMode)

Changes mode of spi.

This function changes mode of spi on fly. Users can send "or"ed BlackLib::spiMode enums as parameter to this function.

Parameters
[in]newModenew mode value
Returns
true if changing operation is successful, else false.
Example
// 0 means SpiDefault. See the BlackLib::spiMode enums.
std::cout << "Current mode: " << (int)mySpi.getMode() << std::endl;
// 3 means SpiPolarity and SpiPhase. See the BlackLib::spiMode enums.
std::cout << "Current mode: " << (int)mySpi.getMode();
// Possible Output:
// Current mode: 0
// Current mode: 3
See also
BlackSpiProperties::spiMode
spiMode
bool BlackLib::BlackSPI::setProperties ( BlackSpiProperties newProperties)

Changes properties of spi.

This function changes properties of spi. These properties are composed of word size, speed and mode.

Parameters
[in]&newPropertiesnew properties of spi
Returns
true if changing operation is successful, else false.
Example
BlackLib::BlackSpiProperties currentProps = mySpi.getProperties();
std::cout << "First bits per word size: " << (int)currentProps.spiBitsPerWord << std::endl
<< "First mode : " << (int)currentProps.spiMode << std::endl
<< "First speed : " << currentProps.spiSpeed << std::endl;
mySpi.setProperties(currentProps);
std::cout << "Second bits per word size: " << (int)currentProps.spiBitsPerWord << std::endl
<< "Second mode : " << (int)currentProps.spiMode << std::endl
<< "Second speed : " << currentProps.spiSpeed << std::endl;
// Possible Output:
// First bits per word size: 8
// First mode : 0
// First speed : 2400000
// Second bits per word size: 10
// Second mode : 3
// Second speed : 18000000
See also
BlackSpiProperties
uint8_t BlackLib::BlackSPI::transfer ( uint8_t  writeByte,
uint16_t  wait_us = 10 
)

Transfers byte to/from slave.

This function creates temporary read variable and then generates SPI IOCTL TRANSFER PACKAGE with write byte's address, temporary read variable's address, delay time, spi word's size and spi speed parameters. After doing ioctl kernel request, if request is finished successfully, data which is held in temporary read variable, is returned from this function.

Parameters
[in]writeByteone byte data
[in]wait_usdelay time
Returns
If transfer operation is successful this function returns received byte data, else returns 0.
Example
uint8_t sendByte = 0x87;
uint8_t recvByte = mySpi.transfer(sendByte, 100);
std::cout << "Loopback spi test result: 0x" << std::hex << (int)recvByte;
// Possible Output:
// Loopback spi test result: 0x87
bool BlackLib::BlackSPI::transfer ( uint8_t *  writeBuffer,
uint8_t *  readBuffer,
size_t  bufferSize,
uint16_t  wait_us = 10 
)

Transfers datas to/from slave.

This function creates temporary read buffer with specified size and then generates SPI IOCTL TRANSFER PACKAGE with write buffer pointer, temporary read buffer pointer, buffer size, delay time, spi word's size and spi speed parameters. After doing ioctl kernel request if request is finished successfully, datas which are held in temporary read buffer are copied to readBuffer pointer.

Parameters
[in]writeBufferdata buffer pointer
[out]readBufferread buffer pointer
[in]bufferSizebuffer size
[in]wait_usdelay time
Returns
true if transfer operation successful, else false.
Example
uint8_t sendBytes[4] = { 0x87, 0x41, 0xF1, 0x5A };
uint8_t recvBytes[4];
mySpi.transfer(sendBytes, recvBytes, sizeof(sendBytes), 100);
std::cout << "Loopback spi test result 0: 0x" << std::hex << (int)recvBytes[0] << std::endl
<< "Loopback spi test result 1: 0x" << std::hex << (int)recvBytes[1] << std::endl
<< "Loopback spi test result 2: 0x" << std::hex << (int)recvBytes[2] << std::endl
<< "Loopback spi test result 3: 0x" << std::hex << (int)recvBytes[3] << std::endl;
// Possible Output:
// Loopback spi test result 0: 0x87
// Loopback spi test result 1: 0x41
// Loopback spi test result 2: 0xF1
// Loopback spi test result 3: 0x5A

Member Data Documentation

BlackSpiProperties BlackLib::BlackSPI::constructorProperties
private

is used to hold the user specified properties of spi

BlackSpiProperties BlackLib::BlackSPI::currentProperties
private

is used to hold the current properties of spi

BlackSpiProperties BlackLib::BlackSPI::defaultProperties
private

is used to hold the default properties of spi

std::string BlackLib::BlackSPI::dtSpiFilename
private

is used to hold the spi's device tree overlay name

bool BlackLib::BlackSPI::isCurrentEqDefault
private

is used to hold the properties of spi is equal to default properties

bool BlackLib::BlackSPI::isOpenFlag
private

is used to hold the spi's tty file's state

int BlackLib::BlackSPI::spiBusNumber
private

is used to hold the spi's bus number

int BlackLib::BlackSPI::spiChipNumber
private

is used to hold the spi's chip number

errorSPI* BlackLib::BlackSPI::spiErrors
private

is used to hold the errors of BlackSPI class

int BlackLib::BlackSPI::spiFD
private

is used to hold the spi's tty file's file descriptor

std::string BlackLib::BlackSPI::spiPortPath
private

is used to hold the spi's tty port path


The documentation for this class was generated from the following files: