Difference between revisions of "Bw tool"

From BitWizard WIKI
Jump to: navigation, search
(installation/compiling)
(Sending Data)
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= intro =
+
= Intro =
  
The bw_tool is meant to provide a basic commandline access to the bitwizard expansion boards. It was written for the raspberry pi, but has now been proven to work on other Linux platforms with an spidev device as well.  
+
The bw_tool is meant to provide a basic commandline access to the bitwizard expansion boards. It was written for the Raspberry Pi, but has now been proven to work on other Linux platforms with an spidev device as well.  
  
= installation/compiling =
+
= Installation/Compiling =
  
 
You can download the bw_tool [https://github.com/rewolff/bw_rpi_tools here]. If you are using git just type  
 
You can download the bw_tool [https://github.com/rewolff/bw_rpi_tools here]. If you are using git just type  
Line 9: Line 9:
  
 
Nowadays the "bw_tool" is the only directory of interest. Go there and build:
 
Nowadays the "bw_tool" is the only directory of interest. Go there and build:
  ''cd bw_tool; make''  
+
  ''cd bw_rpi_tools/bw_tool; make''  
should work fine. If things went smoothly (which they usually do) you can install the binary so that normal people can find it:  
+
should work fine. If things went smoothly (which they usually do) you can install the binary so that normal users on your rpi can find it:  
 
   ''make install''
 
   ''make install''
  
= basic example =
+
== Setting up I2C/SPI under Linux ==
 +
 
 +
On Raspberry pi, raspbian, you first need to edit /boot/config.txt . Near the bottom you will find a line that reads:
 +
#dtparam=i2c_arm=on
 +
You need to remove the hashmark so that it becomes:
 +
dtparam=i2c_arm=on
 +
 
 +
To activate this a reboot is required.
 +
 
 +
Then you need to make sure that the i2c-dev module is loaded. For testing, type:
 +
modprobe i2c-dev
 +
but to make it permantently add "i2c-dev" to /etc/modules .
 +
 
 +
= Basic Example =
  
 
The simplest invocation:
 
The simplest invocation:
Line 21: Line 34:
 
will display the shown text on an SPI_LCD on the default SPI bus (SPI0). Options modify the defaults.
 
will display the shown text on an SPI_LCD on the default SPI bus (SPI0). Options modify the defaults.
  
= about permissions =
+
For example, if you have an I2C module, add:
 +
-I -D /dev/i2c-1
 +
to switch to i2c-mode and specify the correct device.
  
The above command needs access to the SPI bus. By default Linux does not know if letting users access this bus is going to compromise the system or not. So by default Linux chooses to only allow the root user access to the SPI or I2C bus. So you have the following choices:  
+
If you have a rpi_ui plugged onto your raspberry pi, add:
 +
-a 94
  
* You can run your whole session as root. I use "sudo -s" others recommend "sudo su", while "sudo bash" will also work.  
+
= About Permissions =
 +
 
 +
The above command needs access to the SPI bus. By default Linux does not know if letting users access this bus is going to compromise the system or not. As a result, Linux chooses to only allow the root user access to the SPI or I2C bus  by default. So you have the following choices:
 +
 
 +
* You can run your whole session as root. Run "sudo -i" to gain root access.
 
* You can issue only the commands that require spi-bus access as root by prefixing them with "sudo". e.g.:
 
* You can issue only the commands that require spi-bus access as root by prefixing them with "sudo". e.g.:
 
   sudo bw_tool -t "Hello World!"
 
   sudo bw_tool -t "Hello World!"
 +
* If you are using I2C only, you could add yourself to the I2C group (assuming your username is "pi") :
 +
  sudo gpasswd -a pi i2c
 +
or:
 +
  sudo usermod -a -G i2c pi
 +
You only need to run one of these commands once. Afterwards, log out and back in. To verify if the command succeeded, run:
 +
  groups
 +
it should return something like:
 +
  pi adm dialout cdrom sudo audio video plugdev games users '''i2c'''
 
* you can change the permissions on the device files:  
 
* you can change the permissions on the device files:  
 
   sudo chmod 666 /dev/spidev*
 
   sudo chmod 666 /dev/spidev*
 
   sudo chmod 666 /dev/i2c-*
 
   sudo chmod 666 /dev/i2c-*
  
Nowadays the "/dev" filesystem is kept in RAM, not somewhere on disk. So you will need to do that again, at every boot. You could add those commmands to your rc.local (in /etc/) to issue them automatically at every boot. Or you can tell udev that you want those devices world writable. I haven't figured out yet how to do that exactly, so if you want to do the research, feel free to do it that way and report how it's done. (just create a WIKI account and add it here yourself or you can Email to info@ ... and let me do that.)
+
Since the "/dev" filesystem is kept in RAM, you will need to do that again, at every boot. You could add those commands to /etc/rc.local to issue them automatically at every boot, but a better way is to use [https://wiki.debian.org/udev| udev] for this. To do that create (as root) the file /etc/udev/rules.d/70-i2cspi.rules with the following contents:
 +
SUBSYSTEM=="spidev", MODE="0666"
 +
SUBSYSTEM=="i2c-dev", MODE="0666"
 +
and reboot. All I2C and SPI devices should now be world writable.
  
= options =
+
= Options =
  
== options specifying the device ==
+
== Options Specifying the Device ==
  
 
The option  
 
The option  
Line 44: Line 75:
 
The option  
 
The option  
 
  -D <device>  
 
  -D <device>  
will use that device. Specify /dev/spidev0.1 for the second SPI bus on the raspberry pi for example. Or /dev/i2c-1 to specify the second I2C bus. This second i2c bus is the one that is broken out on the gpio's of rev2 raspberry pi's.  
+
will use that device. Specify /dev/spidev0.1 for the second SPI bus on the raspberry pi for example. Or /dev/i2c-1 to specify the second I2C bus. On revision 2 Raspberry Pi's, the I2C buses are switched, so you need -D /dev/i2c-1, while on the first raspberry pi's -D /dev/i2c-0 is redundant as that is the default.
 +
 +
The option
 +
-a <address>
 +
specifies the address of the device to use. Note that BitWizard uses the full 8 bits that are sent to the device. Add one for "read" operation. In some circles, notably I2C, it is customary to specify just those 7 bits. Thus when the I2C_LCD is at the default address of 0x82, i2cdetect will scan it at address 0x41.
  
 
The option
 
The option
  -a <address>
+
  -S
specifies the address of the device to use. Note that BitWizard uses the full 8 bits that are sent to the device. Add one for "read" operation. In some circles, notably I2C, it is customary to specify just those 7 bits. Thus when the I2C_LCD is at the default address of 0x82, i2cdetect will scan it at address 0x41.  
+
will scan the bus for bitwizard protocol devices. This only works for SPI devices. Use the i2cdetect command (in the package i2ctools) to scan the I2C bus if you have i2c devices.
 +
 
 +
== Identifying the Device ==
 +
To check for a proper connection to the device, one could use the identify command line switch -i. For instance, a Raspberry Pi UI connected via I2C could be checked with
 +
bw_tool  -I -D /dev/i2c-0 -a 94 -i
 +
returnes
 +
I2C_rpi_ui 1.6
  
== options sending data ==
+
== Sending Data ==
  
 
the option  
 
the option  
Line 61: Line 102:
  
 
The option
 
The option
  -W <addr>:<short>
+
  -W <addr>:<data>:<type>
will write the 16-bit short to the port at addr. For example -W 81:1000 will write the value 0x1000 to the numsamples port on an analog-equipped board.
+
will write the data to the port at addr, using the datasize specified in "type": b for byte, s for short (16 bits), i for integer (32 bits) and l for long (64 bits) . For example -W 81:1000:s will write the value 0x1000 to the numsamples port on an analog-equipped board.
  
== reading data ==
+
== Reading Data ==
  
 
The option  
 
The option  
Line 70: Line 111:
 
reads the data at port from the device. Datasize can be 'b' for byte (default), 's' for short (16 bits), or 'i' for a 32-bit integer.  
 
reads the data at port from the device. Datasize can be 'b' for byte (default), 's' for short (16 bits), or 'i' for a 32-bit integer.  
  
== finer control ==
+
== Finetuning ==
  
 
To test sending data to SPI devices, there is the  
 
To test sending data to SPI devices, there is the  
 
   --hex [byte...]
 
   --hex [byte...]
option. This simply sends the bytes specified, and reports back what was received. Note that bitwizard boards will not send any data until they have been selected, so the first byte received will represent whatever static is found on the bus.
+
option. This simply sends the bytes specified, and reports back what was received. Note that BitWizard boards will not send any data until they have been selected, so the first byte received will represent whatever static is found on the bus.
 +
 
 +
= Known Bugs =
 +
* The identify command returns two garbled characters when used in I2C mode

Revision as of 13:25, 21 October 2015

Intro

The bw_tool is meant to provide a basic commandline access to the bitwizard expansion boards. It was written for the Raspberry Pi, but has now been proven to work on other Linux platforms with an spidev device as well.

Installation/Compiling

You can download the bw_tool here. If you are using git just type

git clone https://github.com/rewolff/bw_rpi_tools.git 

Nowadays the "bw_tool" is the only directory of interest. Go there and build:

cd bw_rpi_tools/bw_tool; make 

should work fine. If things went smoothly (which they usually do) you can install the binary so that normal users on your rpi can find it:

 make install

Setting up I2C/SPI under Linux

On Raspberry pi, raspbian, you first need to edit /boot/config.txt . Near the bottom you will find a line that reads:

#dtparam=i2c_arm=on 

You need to remove the hashmark so that it becomes:

dtparam=i2c_arm=on

To activate this a reboot is required.

Then you need to make sure that the i2c-dev module is loaded. For testing, type:

modprobe i2c-dev 

but to make it permantently add "i2c-dev" to /etc/modules .

Basic Example

The simplest invocation:

bw_tool -t "Hello World!"

will display the shown text on an SPI_LCD on the default SPI bus (SPI0). Options modify the defaults.

For example, if you have an I2C module, add:

-I -D /dev/i2c-1

to switch to i2c-mode and specify the correct device.

If you have a rpi_ui plugged onto your raspberry pi, add:

-a 94

About Permissions

The above command needs access to the SPI bus. By default Linux does not know if letting users access this bus is going to compromise the system or not. As a result, Linux chooses to only allow the root user access to the SPI or I2C bus by default. So you have the following choices:

  • You can run your whole session as root. Run "sudo -i" to gain root access.
  • You can issue only the commands that require spi-bus access as root by prefixing them with "sudo". e.g.:
 sudo bw_tool -t "Hello World!"
  • If you are using I2C only, you could add yourself to the I2C group (assuming your username is "pi") :
 sudo gpasswd -a pi i2c

or:

 sudo usermod -a -G i2c pi

You only need to run one of these commands once. Afterwards, log out and back in. To verify if the command succeeded, run:

 groups

it should return something like:

 pi adm dialout cdrom sudo audio video plugdev games users i2c
  • you can change the permissions on the device files:
 sudo chmod 666 /dev/spidev*
 sudo chmod 666 /dev/i2c-*

Since the "/dev" filesystem is kept in RAM, you will need to do that again, at every boot. You could add those commands to /etc/rc.local to issue them automatically at every boot, but a better way is to use udev for this. To do that create (as root) the file /etc/udev/rules.d/70-i2cspi.rules with the following contents:

SUBSYSTEM=="spidev", MODE="0666"
SUBSYSTEM=="i2c-dev", MODE="0666"

and reboot. All I2C and SPI devices should now be world writable.

Options

Options Specifying the Device

The option

-I 

will switch to I2C mode.

The option

-D <device> 

will use that device. Specify /dev/spidev0.1 for the second SPI bus on the raspberry pi for example. Or /dev/i2c-1 to specify the second I2C bus. On revision 2 Raspberry Pi's, the I2C buses are switched, so you need -D /dev/i2c-1, while on the first raspberry pi's -D /dev/i2c-0 is redundant as that is the default.

The option

-a <address> 

specifies the address of the device to use. Note that BitWizard uses the full 8 bits that are sent to the device. Add one for "read" operation. In some circles, notably I2C, it is customary to specify just those 7 bits. Thus when the I2C_LCD is at the default address of 0x82, i2cdetect will scan it at address 0x41.

The option

-S

will scan the bus for bitwizard protocol devices. This only works for SPI devices. Use the i2cdetect command (in the package i2ctools) to scan the I2C bus if you have i2c devices.

Identifying the Device

To check for a proper connection to the device, one could use the identify command line switch -i. For instance, a Raspberry Pi UI connected via I2C could be checked with

bw_tool  -I -D /dev/i2c-0 -a 94 -i

returnes

I2C_rpi_ui 1.6

Sending Data

the option

-t "text" 

will send the text to the device, at port zero. The port cannot be changed, but all BitWizard PCBs that have the option of displaying text have the text port at port zero.

The option

-w <addr>:<byte> 

will write the byte to the port at addr. For LCD-equipped boards for example -w 12:50 will set the contrast to 0x50.

The option

-W <addr>::<type>

will write the data to the port at addr, using the datasize specified in "type": b for byte, s for short (16 bits), i for integer (32 bits) and l for long (64 bits) . For example -W 81:1000:s will write the value 0x1000 to the numsamples port on an analog-equipped board.

Reading Data

The option

-R <port>:<datasize>

reads the data at port from the device. Datasize can be 'b' for byte (default), 's' for short (16 bits), or 'i' for a 32-bit integer.

Finetuning

To test sending data to SPI devices, there is the

 --hex [byte...]

option. This simply sends the bytes specified, and reports back what was received. Note that BitWizard boards will not send any data until they have been selected, so the first byte received will represent whatever static is found on the bus.

Known Bugs

  • The identify command returns two garbled characters when used in I2C mode