xref: /openbmc/linux/drivers/staging/pi433/Documentation/pi433.txt (revision f0c7686d)

=====
Pi433
=====


Introduction
============
This driver is for controlling pi433, a radio module for the Raspberry Pi
(www.pi433.de). It supports transmission and reception. It can be opened
by multiple applications for transmission and reception. While transmit
jobs are queued and processed automatically in the background, the first
application asking for reception will block out all other applications
until something gets received terminates the read request.
The driver supports on the fly reloading of the hardware fifo of the rf
chip, thus enabling for much longer telegrams than the hardware fifo size.

Description of driver operation
===============================

a) transmission

Each transmission can take place with a different configuration of the rf
module. Therefore each application can set its own set of parameters. The driver
takes care, that each transmission takes place with the parameterset of the
application, that requests the transmission. To allow the transmission to take
place in the background, a tx thread is introduced.
The transfer of data from the main thread to the tx thread is realised by a
kfifo. With each write request of an application, the passed in data and the
corresponding parameter set gets written to the kfifo.
On the other "side" of the kfifo, the tx thread continuously checks, whether the
kfifo is empty. If not, it gets one set of config and data from the kfifo. If
there is no receive request or the receiver is still waiting for something in
the air, the rf module is set to standby, the parameters for transmission gets
set, the hardware fifo of the rf chip gets preloaded and the transmission gets
started. Upon hardware fifo threshold interrupt it gets reloaded, thus enabling
much longer telegrams than the hardware fifo size. If the telegram is sent and there
is more data available in the kfifo, the procedure is repeated. If not the
transmission cycle ends.

b) reception

Since there is only one application allowed to receive data at a time, for
reception there is only one configuration set.
As soon as an application sets a request for receiving a telegram, the reception
configuration set is written to the rf module and it gets set into receiving mode.
Now the driver is waiting, that a predefined RSSI level (signal strength at the
receiver) is reached. Until this hasn't happened, the reception can be
interrupted by the transmission thread at any time to insert a transmission cycle.
As soon as the predefined RSSI level is met, a receiving cycle starts. Similar
as described for the transmission cycle the read out of the hardware fifo is done
dynamically. Upon each hardware fifo threshold interrupt, a portion of data gets
read. So also for reception it is possible to receive more data than the hardware
fifo can hold.


Driver API
==========

The driver is currently implemented as a character device. Therefore it supports
the calls open, ioctl, read, write and close.


params for ioctl
----------------

There are four options:
PI433_IOC_RD_TX_CFG - get the transmission parameters from the driver
PI433_IOC_WR_TX_CFG - set the transmission parameters
PI433_IOC_RD_RX_CFG - get the receiving parameters from the driver
PI433_IOC_WR_RX_CFG - set the receiving parameters

The tx configuration is transferred via struct pi433_tx_cfg, the parameterset for transmission.
It is divided into two sections: rf parameters and packet format.

rf params:
	frequency
		frequency used for transmission.
		Allowed values: 433050000...434790000
	bit_rate
		bit rate used for transmission.
		Allowed values: #####
	dev_frequency
		frequency deviation in case of FSK.
		Allowed values: 600...500000
	modulation
		FSK - frequency shift key
		OOK - On-Off-key
	modShaping
		shapingOff	- no shaping
		shaping1_0	- gauss filter with BT 1 (FSK only)
		shaping0_5	- gauss filter with BT 0.5 (FSK only)
		shaping0_3	- gauss filter with BT 0.3 (FSK only)
		shapingBR	- filter cut off at BR (OOK only)
		shaping2BR	- filter cut off at 2*BR (OOK only)
	pa_ramp (FSK only)
		ramp3400	- amp ramps up in 3.4ms
		ramp2000	- amp ramps up in 2.0ms
		ramp1000	- amp ramps up in 1ms
		ramp500		- amp ramps up in 500us
		ramp250		- amp ramps up in 250us
		ramp125		- amp ramps up in 125us
		ramp100		- amp ramps up in 100us
		ramp62		- amp ramps up in 62us
		ramp50		- amp ramps up in 50us
		ramp40		- amp ramps up in 40us
		ramp31		- amp ramps up in 31us
		ramp25		- amp ramps up in 25us
		ramp20		- amp ramps up in 20us
		ramp15		- amp ramps up in 15us
		ramp12		- amp ramps up in 12us
		ramp10		- amp ramps up in 10us
	tx_start_condition
		fifo_level	- transmission starts, if fifo is filled to
				  threshold level
		fifo_not_empty	- transmission starts, as soon as there is one
				  byte in internal fifo
	repetitions
		This gives the option, to send a telegram multiple times. Default: 1

packet format:
	enable_preamble
		optionOn	- a preamble will be automatically generated
		optionOff	- no preamble will be generated
	enable_sync
		optionOn	- a sync word will be automatically added to
				  the telegram after the preamble
		optionOff	- no sync word will be added
		Attention: While possible to generate sync without preamble, the
		receiver won't be able to detect the sync without preamble.
	enable_length_byte
		optionOn	- the length of the telegram will be automatically
				  added to the telegram. It's part of the payload
		optionOff	- no length information will be automatically added
				  to the telegram.
		Attention: For telegram length over 255 bytes, this option can't be used
		Attention: should be used in combination with sync, only
	enable_address_byte
		optionOn	- the address byte will be automatically added to the
				  telegram. It's part of the payload
		optionOff	- the address byte will not be added to the telegram.
		The address byte can be used for address filtering, so the receiver
		will only receive telegrams with a given address byte.
		Attention: should be used in combination with sync, only
	enable_crc
		optionOn	- an crc will be automatically calculated over the
				  payload of the telegram and added to the telegram
				  after payload.
		optionOff	- no crc will be calculated
	preamble_length
		length of the preamble. Allowed values: 0...65536
	sync_length
		length of the sync word. Allowed values: 0...8
	fixed_message_length
		length of the payload of the telegram. Will override the length
		given by the buffer, passed in with the write command. Will be
		ignored if set to zero.
	sync_pattern[8]
		contains up to eight values, that are used as the sync pattern
		on sync option
	address_byte
		one byte, used as address byte on address byte option.


The rx configuration is transferred via struct pi433_rx_cfg, the parameterset for receiving. It is divided into two sections: rf parameters and packet format.

rf params:
	frequency
		frequency used for transmission.
		Allowed values: 433050000...434790000
	bit_rate
		bit rate used for transmission.
		Allowed values: #####
	dev_frequency
		frequency deviation in case of FSK.
		Allowed values: 600...500000
	modulation
		FSK - frequency shift key
		OOK - on off key
	rssi_threshold
		threshold value for the signal strength on the receiver input.
		If this value is exceeded, a reception cycle starts
		Allowed values: 0...255
	threshold_decrement
		in order to adapt to different levels of singnal strength, over
		time the receiver gets more and more sensitive. This value
		determs, how fast the sensitivity increases.
		step_0_5db	- increase in 0,5dB steps
		step_1_0db	- increase in 1 db steps
		step_1_5db	- increase in 1,5dB steps
		step_2_0db	- increase in 2 db steps
		step_3_0db	- increase in 3 db steps
		step_4_0db	- increase in 4 db steps
		step_5_0db	- increase in 5 db steps
		step_6_0db	- increase in 6 db steps
	antenna_impedance
		sets the electrical adoption of the antenna
		fifty_ohm	- for antennas with an impedance of 50Ohm
		two_hundred_ohm	- for antennas with an impedance of 200Ohm
	lna_gain
		sets the gain of the low noise amp
		automatic	- lna gain is determined by an agc
		max		- lna gain is set to maximum
		max_minus_6	- lna gain is set to  6db below max
		max_minus_12	- lna gain is set to 12db below max
		max_minus_24	- lna gain is set to 24db below max
		max_minus_36	- lna gain is set to 36db below max
		max_minus_48	- lna gain is set to 48db below max
	bw_mantisse
		sets the bandwidth of the channel filter - part one: mantisse.
		mantisse16	- mantisse is set to 16
		mantisse20	- mantisse is set to 20
		mantisse24	- mantisse is set to 24
	bw_exponent
		sets the bandwidth of the channel filter - part two: exponent.
		Allowd values: 0...7
	dagc;
		operation mode of the digital automatic gain control
		normal_mode
		improve
		improve_for_low_modulation_index

 packet format:
	enable_sync
		optionOn  - sync detection is enabled. If configured sync pattern
			    isn't found, telegram will be internally discarded
		optionOff - sync detection is disabled.
	enable_length_byte
		optionOn   - First byte of payload will be used as a length byte,
			     regardless of the amount of bytes that were requested
			     by the read request.
		optionOff  - Number of bytes to be read will be set according to
			     amount of bytes that were requested by the read request.
		Attention: should be used in combination with sync, only
	enable_address_filtering;
		filtering_off		  - no address filtering will take place
		node_address		  - all telegrams, not matching the node
					    address will be internally discarded
		node_or_broadcast_address - all telegrams, neither matching the
					    node, nor the broadcast address will
					    be internally discarded
		Attention: Sync option must be enabled in order to use this feature
	enable_crc
		optionOn	- a crc will be calculated over the payload of
				  the telegram, that was received. If the
				  calculated crc doesn't match to two bytes,
				  that follow the payload, the telegram will be
				  internally discarded.
		Attention: This option is only operational if sync on and fixed length
		or length byte is used
	sync_length
		Gives the length of the payload.
		Attention: This setting must meet the setting of the transmitter,
		if sync option is used.
	fixed_message_length
		Overrides the telegram length either given by the first byte of
		payload or by the read request.
	bytes_to_drop
		gives the number of bytes, that will be dropped before transferring
		data to the read buffer
		This option is only useful if all packet helper are switched
		off and the rf chip is used in raw receiving mode. This may be
		needed, if a telegram of a third party device should be received,
		using a protocol not compatible with the packet engine of the rf69 chip.
	sync_pattern[8]
		contains up to eight values, that are used as the sync pattern
		on sync option.
		This setting must meet the configuration of the transmitting device,
		if sync option is enabled.
	node_address
		one byte, used as node address byte on address byte option.
	broadcast_address
		one byte, used as broadcast address byte on address byte option.