 |
|
You are here: GSI Wiki>Epics Web>EpicsProjectsAndActivities>HardwarePlatforms>HadCon2>HadCon2MultipurposeControlsApi>HadConMultipurposeControlsProtocol>HadConMultipurposeControlsProtocolCmndSpi (2020-11-09, PeterZumbruch)Edit Attach
HadCon Multipurpose Controls Protocol Cmnd Spi
Introduction
Command descriptions of commandSPI
SPI
Api Basic Operation Principle
- automatically ( Basic Operation ),
- semi-automatically ( Advanced Operation ), or
- manually ( Expert Operation )
- "Single Command Operation"
- All necessary steps are taken automatically, optional behavior can be achieved by changing the configuration.
- optionally purge read buffer
- (default
- TRUE)
- purge write buffer
- filling the write buffer
by decomposing input byte by byte
⇒dc 7f 8f 8f b4 01 23 45 67 89 ab cd ef be - set cs
- setting the defined chip-select pin(s) to "active low"
- optionally masked by an external mask
- setting the defined chip-select pin(s) to "active low"
- transmit/receive
byte by byte in the given byte-order- transmit write buffer content
- attaching received bytes to the end of the read buffer
- release cs
- release the defined chip-select pins(s) to "passive high"
- optionally masked by an external mask
- release the defined chip-select pins(s) to "passive high"
- optionally purge write buffer
(default: FALSE) - last read element
SPI read
- last read 3 elements
SPI show_read_buffer 3 1
- first read 6 elements
SPI show_read_buffer 6
- the full content
SPI show_read_buffer - set cs
- setting the defined chip-select pin(s) to "active low"
- optionally masked by an external mask
- setting the defined chip-select pin(s) to "active low"
- transmit/receive
byte by byte in the given byte-order- transmit write buffer content
- attaching received bytes to the end of the read buffer
- release cs
- release the defined chip-select pins(s) to "passive high"
- optionally masked by an external mask
- release the defined chip-select pins(s) to "passive high"
- optionally purge write buffer
General Operation
The
SPI command set allows to operate the Serial Peripheral Interface SPI interface of the HadCon(2)'s microcontroller, (currently "only") as a master.
It sends data in atomic chunks of bytes via the MOSI pin to slave devices and receives via the MISO pin the responses.
This happens in a buffered mode, so that multiple bytes can be send and received at once. The current limitation of the write-buffer is linked to the input string buffer of 140 characters, i.e. ≈ 60 bytes. Up to 8 Chip-Select/SlaveS Select output pin(s) can be defined and manipulated either
Basic Operation
SPI write dc 7f 8f8fb4 0123456789abcdef be
SPI dc 7f 8f8fb4 0123456789abcdef be
write command includes the following steps: Advanced Operation
-
The user can prepare step by step the write buffer before automatically sending it.
Example sequence: add/write_buffer
TheSPI purge_read_buffer// optionallySPI purge_write_buffer// optionallySPI add dc 7f SPI add 8f8fb4// repeat until write buffer is fullSPI add 0123456789abcdef//SPI add be//SPI show_write_buffer// optionallySPI write_buffer SPI write_buffer// e.g. repeat it, if auto_purge is OFFSPI write_buffer 02// only activate second chip select pin, by masking it with 0x02
write_buffer command includes all remaining necessary steps: Reading: see Basic OperationSPI write dc 7f 8f8fb4 0123456789abcdef be SPI write_buffer// e.g. repeat it, if auto_purge is OFF... SPI write_buffer SPI write_buffer 02// only activate 2nd chip select pin, by masking it with 0x02SPI write_buffer 01// only activate 1st chip select pinSPI write_buffer fc// only activate the other chip select pins
Expert Operation
-
The user has full control on setting and releasing chip select pins.
Example sequence: selected chip select
Reading: see Basic OperationSPI purge_read_buffer// optionallySPI purge_write_buffer// optionallySPI add dc 7f 8f8fb4 0123456789abcdef be SPI cs// get status of defined chip select pinsSPI cs_bar// same as above but with "active low" logicSPI cs_set// set all available chip select pins to "active"SPI transmit SPI cs_release// set all available chip select pins to "passive"SPI cs_set 01// only activate 1st chip select pin to "active"SPI transmit SPI cs_release// set all available chip select pins to "passive"SPI cs_set fe// only activate the other chip select pins to "active"SPI transmit SPI cs_release ee// set masked chip select pins to "passive", keep 5th "active"SPI cs_release 10// set masked chip select pins to "passive", keep 5th "active"
- Task
- send list of bytes to clients, including predefined purge, chip-select behavior
- Format
-
-
SPI write<list of data bytes|words|dwords|qwords> -
SPI w<list of data bytes|words|dwords|qwords>
-
- Response
-
- nothing
- if
DEBG> 0RECV SPI write OK
- Description
-
As described in section Basic Operation- Arguments
-
- list of data bytes|words|dwords|qwords|...
- Comments
-
- Maximum single number length 24 digits
- only byte-wise sending allowed
- see SPI cs_select_mask
- see SPI auto_purge_write_buffer
- see SPI auto_purge_read_buffer
- see SPI transmit_report
- see SPI transmit_byte_order
- Task
- send write buffer content to clients, including predefined purge, chip-select behavior,
optionally selecting chip select pins - Format
-
-
SPI write_buffer[ <Chip Select Mask> ] -
SPI wb[ <Chip Select Mask> ]
-
- Response
-
RECV SPI write_buffer
- Description
-
- Arguments
-
- optional: external chip select mask:
- [ 0 ... FF]
- each bit represents a cs pin
- 1:active, 0:inactive
- optional: external chip select mask:
- Comments
- Task
- sets (selected) chip select pins to "active low"
- Format
-
-
SPI cs_set[ <Chip Select Mask> ] -
SPI css[ <Chip Select Mask> ]
-
- Response
-
RECV SPI cs 1:1 2:- 3:- 4:- 5:- 6:- 7:- 8:-
- Description
- On success
csis called to show the current status- Arguments
-
- optional: external chip select mask:
- [ 0 ... FF]
- each bit represents a cs pin
- 1:active, 0:inactive
- optional: external chip select mask:
- Comments
- Task
- releases (selected) chip select pins to "passive high"
- Format
-
-
SPI cs_release[ <Chip Select Mask> ] -
SPI csr[ <Chip Select Mask> ]
-
- Response
-
RECV SPI cs 1:1 2:- 3:- 4:- 5:- 6:- 7:- 8:-
- Description
-
- Arguments
-
- optional: external chip select mask:
- [ 0 ... FF]
- each bit represents a cs pin
- 1:active, 0:inactive
- optional: external chip select mask:
- Comments
- Task
- read the last element filled into the read buffer
- Format
-
-
SPI read -
SPI r
-
- Response
-
RECV SPI read <value>
- Description
- read the last element filled into the read buffer
depending on the transmit_byte_order : * 0, MSB: last element (FIFO) * 1, LSB: first element (LIFO)- Arguments
-
- -
- Return values
-
-
<value>- "--" , if read buffer is empty
- last byte filled [0 .. FF]
-
- Comments
- Task
- show (partial) content of read buffer
- Format
-
-
SPI show_read_buffer[<Number of Bytes> [<Reverse Flag>]] -
SPI sr[<Number of Bytes> [<Reverse Flag>]]
-
- Response
-
- w/o any arguments,
buffer filled, ≤ 8 bytes:
SPI sr
RECV SPI show_read_buffer elements: 0x5 (5)
RECV SPI show_read_buffer 10 00 10 21 42 - w/o any arguments,
buffer filled, > 8 bytes:
SPI sr
RECV SPI show_read_buffer elements: 0x14 (20)
RECV SPI show_read_buffer (#1) 10 00 10 21 42 51 25 01 ...
RECV SPI show_read_buffer (#2) 10 10 10 00 10 21 42 51 ...
RECV SPI show_read_buffer (#3) 25 01 10 10 - w/
<Number of Bytes>set,<Number of Bytes>≠0,
buffer empty:
SPI sr 3
RECV SPI show_read_buffer -- - w/
<Number of Bytes>set, e.g. 4,
buffer filled, ≤ 8 bytes:
SPI sr 4
RECV SPI show_read_buffer 10 00 10 21 - w/
<Number of Bytes>set, e.g. 0xA,
buffer filled, > 8 bytes:
SPI sr a
RECV SPI show_read_buffer (#1) 10 00 10 21 42 51 25 01 ...
RECV SPI show_read_buffer (#2) 10 10 - w/
<Number of Bytes>set, e.g. 2,
w/<Reverse Flag>flag set (TRUE,HIGH,ON,1)
buffer filled, ≤ 8 bytes,
SPI sr 2 TRUE
RECV SPI show_read_buffer 10 10 - w/
<Number of Bytes>set, e.g. 9,
w/<Reverse Flag>flag set (TRUE,HIGH,ON,1)
buffer filled, > 8 bytes:
SPI sr 9 1
RECV SPI show_read_buffer (#1) 00 10 21 42 51 25 01 10 ...
RECV SPI show_read_buffer (#2) 10
- w/o any arguments,
- Description
- Shows (partial) content of read buffer. Depending on the optional arguments the set can be reduced to a sub set of the buffer, beginning from the first element filled or reverse beginning with the last elements added. Depending on the number of elements requested, additional information is added:
- if all elements are show a summary line is added, with the given number of elements in the buffer in hex and decimal
- if the number of elements to show exceed
8- a line counter
(#i), starting from 1, is added in front - "..." are added at the end of the line, if more lines follow
- a line counter
- Arguments
-
-
<Number of Bytes>- max number of bytes to show, ≥ 0
-
0: all available - else: show
<Number of Bytes>elements from beginning (1) to maximum<Number of Bytes>
-
- max number of bytes to show, ≥ 0
-
<Reverse Flag>- flag to revert direction of interest
-
0,FALSE,OFF,LOW: show<Number of Bytes>elements from beginning (1) to maximum<Number of Bytes> - else: show
<Number of Bytes>elements from<number of elements> - <Number of Bytes>until last added element
-
- flag to revert direction of interest
-
- Comments
-
- -
Main Commands
SPI w/write
SPI wb/write_buffer
SPI css/cs_set
SPI csr/cs_release
SPI r/read
SPI sr/show_read_buffer
- Task
- purge read buffer
- Format
-
-
SPI purge_read_buffer -
SPI pr
-
- Response
-
- nothing
- if
DEBG> 0RECV SPI purge_read_buffer OK
- Description
-
- Arguments
-
- -
- Comments
-
- only resets the number of elements to 0, not the data
Clean-up
SPI pr/purge_read_buffer
- Task
- reports current status of (selected) chip select lines
- Format
-
-
SPI cs[<Chip Select Mask>]
-
- Response
-
- w/o mask
SPI cs
RECV SPI cs 1:0 2:- 3:- 4:- 5:- 6:- 7:- 8:-
- w/ mask, eg.
0b01100001 = 0x71
SPI cs 71
RECV SPI cs 1:0 6:- 7:-
- w/o mask
- Description
-
- Arguments
-
- optional
[<Chip Select Mask>]- [ 0 ... FF]
- each bit represents a cs pin
- 1:chosen, 0:ignore
- optional
- Response
-
- list of
<Pin States>- syntax
<Pin States>:-
<Index>:<State>-
<Index>:1 ... 8 -
<State>:-
1: HIGH -
0: LOW -
-: undefined, channel not connected
-
-
-
- syntax
- list of
- Comments
-
- -
- Task
- reports current inverted status of (selected) chip select lines
- Format
-
-
SPI cs_bar[<Chip Select Mask>] -
SPI csb[<Chip Select Mask>]
-
- Response
-
- w/o mask
SPI csb
RECV SPI cs_bar 1:1 2:- 3:- 4:- 5:- 6:- 7:- 8:-
- w/ mask, eg.
0b01100001 = 0x71
SPI csb 71
RECV SPI cs_bar 1:1 6:- 7:-
- w/o mask
- Description
-
- Arguments
-
- optional
<Chip Select Mask>- [ 0 ... FF]
- each bit represents a cs channel/pin
- 1:chosen, 0:ignore
- optional
- Response
-
- list of
<Pin States>- syntax
<Pin States>:-
<Index>:<State>-
<Index>:1 ... 8 -
<State>:-
1: LOW -
0: HIGH -
-: undefined, channel not connected
-
-
-
- syntax
- list of
- Task
- report current chip select channel configurations
- Format
-
-
SPI cs_pins[<CS Channel Index>]
-
- Response
-
- w/o argument
SPI cs_pins
RECV SPI cs_pins <List of active <Index>:<PORTx>,<Pin> CS Configurations>- e.g.:
RECV SPI cs_pins 1:PORTB,0 2:PORTA,4 3:PORTG,4 7:PORTF,5
- e.g.:
- w/
<CS Channel Index>
SPI cs_pins<CS Channel Index>
RECV SPI cs_pins <Index><PORTx>,<Pin>,<Status>- e.g.:
SPI cs_pins 1
RECV SPI cs_pins 1:PORTB,0,ON
- e.g.:
- w/o argument
- Description
-
- Arguments
-
- optional
<CS Channel Index>- chip select index
-
1 ... 8
- optional
- Return values
-
-
<List of active <Index>:<PORTx>,<Pin> CS Configurations>
or
<<Index>:<PORTx>,<Pin>,<Status> CS Configuration>-
<Index>- chip select index
-
1 ... 8
-
<PORTx>-
PORTx-
x:A ... G
-
-
-
<Pin>- pin number of
PORTx-
0 ... 7
-
- pin number of
-
<Status>- status of chosen chip select index
-
ON: active -
OFF: deactivated
-
- status of chosen chip select index
-
-
- Comments
Status
SPI cs
SPI csb/cs_bar
SPI cs_pins
- Task
- add chip select channel configuration
- Format
-
-
SPI cs_add_pin<Symbolic Output Port Address> <Output Port Pin> [<Channel Select Index/Slot>] -
SPI csap<Symbolic Output Port Address> <Output Port Pin> [<Channel Select Index/Slot>]
-
- Response
- see SPI cs_pins
RECV SPI cs_pins <List of active <Index>:<PORTx>,<Pin> CS Configurations> - Description
- Allows to add up to 8 output port
PORTX:Pincombinations to act as channel select channels. Provided the chosen slots aren't used yet or the address set is already defined (see SPI cs_pins, SPI cs_remove_pin).
A successful operation is reported via SPI cs_pins- w/o
<Channel Select Index/Slot>:- adds channel to next free slot
- w/
<Channel Select Index/Slot>:- adds channel to assigned index
- Arguments
-
-
<Symbolic Output Port Address> - symbolic name for the available output port addresses
-
PORTx-
x:A ... G
-
-
-
<Output Port Pin>- pin number of
PORTx-
0 ... 7
-
- pin number of
- optionally
<Channel Select Index/Slot>- chip select index
-
1 ... 8
-
- chip select index
-
- w/o
- Comments
-
- see SPI cs_pins
- see SPI cs_remove_pin
- Task
- remove chip select channel configuration
- Format
-
-
SPI cs_remove_pin<Channel Select Index/Slot> -
SPI csrp<Channel Select Index/Slot>
-
- Response
- see SPI cs_pins
RECV SPI cs_pins <List of active <Index>:<PORTx>,<Pin> CS Configurations> - Description
- Removes a chip select configuration from set of pin configuration (see SPI cs_pins).
A successful operation is reported via SPI cs_pins.- Arguments
-
-
<Channel Select Index/Slot>- chip select index
-
1 ... 8
-
- chip select index
-
- Comments
-
- see SPI cs_pins
- see SPI cs_add_pin
Chip Select Configuration
SPI csap/cs_add_pin
SPI csrp/cs_remove_pin
- Task
- set/get SPI hardware configuraton/status
- Format
-
-
SPI control_bits[<Extended SPI Control Register>] -
SPI c[<Extended SPI Control Register>]
-
- Response
- e.g. :
RECV SPI control_bits 50
RECV SPI spi_enable TRUE
RECV SPI data_order 0
RECV SPI master TRUE
RECV SPI clock_polarity 0
RECV SPI clock_phase 0
RECV SPI speed 0
RECV SPI double_speed TRUE
RECV SPI speed_divider 4 (2500000Hz @ 10000000Hz) - Description
- Allows to set/get the combined information/settings of the SPI Control Register
SPCRand the SPI Status RegisterSPSRen bloc. Therefore those two registers are combinded into one 16bit data word withSPCRas LSB andSPSRas MSB. SinceSPSR, despite its name, does have one control bit.
- w/o
<Extended SPI Control Register>:- reports status
- w/
<Extended SPI Control Register>:- changes configuration
- Note
- all settings can be done alone using the functions described below. Success is reported via its get mode and the get functions of the seperate properties.
- Arguments
-
-
<Extended SPI Control Register>-
0 ... 1FF
-
-
- w/o
- Comments
-
- See SPI spi_enable
- See SPI data order
- See SPI master
- See SPI clock polarity
- See SPI clock phase
- See SPI speed
- See SPI speed divider
- See SPI double speed
- Task
- get/set spi configuration's bit
SPI enable state: SPE - Format
-
-
SPI spi_enable[<value>]
-
- Response
-
RECV SPI spi_enable ==SPI enable state: SPE==
- Description
- "When the SPE bit is written to one, the SPI is enabled. This bit must be set to enable any SPI operation."
(from Manual: AT90CANxx)- w/o argument: get value
- w/ argument: set value
- Arguments
-
-
<value>-
0, 1, ≠0, ON, OFF, TRUE, FALSE
-
-
- Comments
-
- -
- Task
- get/set spi configuration's bit
SPI Data Order: DORD - Format
-
-
SPI data_order[<value>]
-
- Response
-
RECV SPI data_order
- Description
- "When the DORD bit is written to one, the LSB of the data word is transmitted first. When the DORD bit is written to zero, the MSB of the data word is transmitted first. "
(from Manual: AT90CANxx)- w/o argument: get value
- w/ argument: set value
- Arguments
-
-
<value>-
0, 1, ≠0, ON, OFF, TRUE, FALSE
-
-
- Comments
-
- Don't mix up with API's transmit_byte_order
- Task
- get/set spi configuration's bit
SPI Master/Slave Select: MSTR - Format
-
-
SPI master[<value>]
-
- Response
-
RECV SPI master
- Description
- "This bit selects Master SPI mode when written to one, and Slave SPI mode when written logic zero. If SS [the 'Chip Select Pin'] is configured as an input and is driven low while MSTR is set, MSTR will be cleared"
(from Manual: AT90CANxx)- w/o argument: get value
- w/ argument: set value
- Arguments
-
-
<value>-
(0,) 1, ≠0, ON, (OFF), TRUE, (FALSE)
-
-
- Comments
-
- Slave mode not implemented
- Task
- get/set spi configuration's bit
SPI Clock Polarity: CPOL - Format
-
-
SPI clock_polarity[<value>]
-
- Response
-
RECV SPI clock_polarity
- Description
- "When this bit is written to one, SCK is high when idle. When CPOL is written to zero, SCK is low when idle."
(from Manual: AT90CANxx)-
CPOL Leading Edge Trailing Edge 0 Rising Falling 1 Falling Rising - w/o argument: get value
- w/ argument: set value
- Arguments
-
-
<value>-
0, 1, ≠0, ON, OFF, TRUE, FALSE
-
-
-
- Comments
-
- -
- Task
- get/set spi configuration's bit
SPI Clock Phase: CPHA - Format
-
-
SPI clock_phase[<value>]
-
- Response
-
RECV SPI clock_phase
- Description
- "The settings of the Clock Phase bit (CPHA) determine if data is sampled on the leading (first) or trailing (last) edge of SCK."
(from Manual: AT90CANxx)CPHA Leading Edge Trailing Edge 0 Sample Setup 1 Setup Sample - w/o argument: get value
- w/ argument: set value
- Arguments
-
-
<value>-
0, 1, ≠0, ON, OFF, TRUE, FALSE
-
-
- Comments
-
- -
- Task
- get/set spi configuration's bits
SPI Clock Rate Select 1/0: SPR1/0 - Format
-
-
SPI speed[<value>]
-
- Response
-
RECV SPI speed
- Description
- "These two bits control the SCK rate of the device configured as a Master. SPR1 and SPR0 have no effect on the Slave. "
(from Manual: AT90CANxx)- w/o argument: get value
- w/ argument: set value
- Arguments
-
-
<value>-
0 ... 3 -
speed double speed clock rate: SCK frequency 0OFFfclkIO/4 1OFFfclkIO/16 2OFFfclkIO/64 3OFFfclkIO/128 0ONfclkIO/2 1ONfclkIO/8 2ONfclkIO/32 3ONfclkIO/64
-
-
- Comments
-
- See SPI double speed
- Task
- get/set spi configuration's bit
SPI Double Speed Bit:SPI2X - Format
-
-
SPI double_speed[<value>]
-
- Response
-
RECV SPI double_speed
- Description
- "When this bit is written logic one the SPI speed (SCK Frequency) will be doubled when the SPI is in Master mode. This means that the minimum SCK period will be two CPU clock periods. When the SPI is configured as Slave, the SPI is only guaranteed to work at fclkio/4 or lower."
(from Manual: AT90CANxx)- w/o argument: get value
- w/ argument: set value
- Arguments
-
-
<value>-
0, 1, ≠0, ON, OFF, TRUE, FALSE
-
-
- Comments
-
- -
SPI Configuration
SPI c/control_bits
SPI spi_enable
SPI data_order
SPI master
SPI clock_polarity
SPI clock_phase
SPI speed
SPI speed_divider
SPI double_speed
- Task
- get/set the transmit order the data bytes of the buffer are written to the devices
- Format
-
-
SPI transmit_byte_order[<value>]
-
- Response
-
RECV SPI transmit_byte_order
- Description
-
- w/o argument: get value
- w/ argument: set value
- Arguments
-
-
<value>-
0, 1
<value> transmit byte order 0 MSB, big endian, FIFO 1 LSB, little endian, LIFO
-
-
- Comments
-
- -
- Task
- get status of / enable/disable additional transmission reports after sending the write buffer
- Format
-
-
SPI transmit_report[<value>]
-
- Response
- $ Description:
RECV SPI transmit_report
- w/o argument: get value
- w/ argument: set value
- Arguments
-
-
<value>-
0, 1, ≠0, ON, OFF, TRUE, FALSE
-
-
- Comments
-
- -
- Task
- get status of / enable/disable automatic write buffer purge after sending its content
- Format
-
-
SPI auto_purge_write_buffer[<value>]
-
- Response
- $ Description:
RECV SPI auto_purge_write_buffer
- w/o argument: get value
- w/ argument: set value
- Arguments
-
-
<value>-
0, 1, ≠0, ON, OFF, TRUE, FALSE
-
-
- Comments
-
- -
- Task
- get status of / enable/disable automatic read buffer purge before sending data
- Format
-
-
SPI auto_purge_read_buffer[<value>]
-
- Response
- $ Description:
RECV SPI auto_purge_read_buffer
- w/o argument: get value
- w/ argument: set value
- Arguments
-
-
<value>-
0, 1, ≠0, ON, OFF, TRUE, FALSE
-
-
- Comments
-
- -
API Configuration
SPI transmit_byte_order
SPI transmit_report
SPI auto_purge_write_buffer
SPI auto_purge_read_buffer
-- PeterZumbruch - 13 Jan 2014
-- PeterZumbruch - 2020-11-09
Edit | Attach | Print version | History: r17 < r16 < r15 < r14 | Backlinks | View wiki text | Edit wiki text | More topic actions
Topic revision: r17 - 2020-11-09, PeterZumbruch
- User Reference
- BeginnersStartHere
- EditingShorthand
- Macros
- MacrosQuickReference
- FormattedSearch
- QuerySearch
- DocumentGraphics
- SkinBrowser
- InstalledPlugins
- Admin Maintenance
- Reference Manual
- AdminToolsCategory
- InterWikis
- ManagingWebs
- SiteTools
- DefaultPreferences
- WebPreferences
- Categories
Aikido
Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors. Ideas, requests, problems regarding GSI Wiki? Send feedback | Legal notice | Privacy Policy (german)