BiSS / SSI Encoder Module

This module provides functions to read data transmitted using the BiSS protocol and process the data coming from a BiSS Encoder into position data. The module is also compatible with SSI encoders.

BiSS is an open source digital interface for sensors and actuators. BiSS is hardware compatible to the industrial standard SSI (Serial Synchronous Interface). The standardization process is coordinated on biss-interface.com.

Those functions are used in Serial Encoder Module itself used by Position Feedback Module to create a service for reading a BiSS or SSI encoders.

The BiSS functions should always run over an IF2 Tile so it can access the ports to your SOMANET Drive module.

How to use

Important

We assume that you are using SOMANET Base and your app includes the required board support files for your SOMANET device.

See also

You might find useful the BiSS Sensor Demo and SSI Sensor Demo, which illustrates the use of this module.

  1. First, add all the SOMANET Motor Control modules to your app Makefile.

    USED_MODULES = configuration_parameters module_adc module_biss_encoder lib_bldc_torque_control module_board-support module_hall_sensor module_utils module_position_feedback module_pwm module_incremental_encoder module_encoder_rem_14 module_encoder_rem_16mt module_serial_encoder module_shared_memory module_spi_master module_watchdog
    

    Note

    Not all modules will be required, but when using a library it is recommended to include always all the contained modules. This will help solving internal dependency issues.

  2. Include the BiSS Service header biss_service.h in your app.

  3. Instantiate the ports for the BiSS.

    BiSS needs a clock output port, a data input port and a clock block. The read function takes pointers for parameters, so you need to pass the addresses of the ports. The biss_clock_low and biss_clock_high parameters need to be set. When the clock port is a 1-bit port they should be 0 and 1. When the clock port is more than 1 bit and the other bits are used for external config biss_clock_low and biss_clock_high should be set accordingly.

  4. Fill up the BiSS configuration structure. BiSS and SSI use the same parameters. The protocol type is selected with the position_feedback_config.sensor_type parameters. Usually SSI encoders don’t support CRC or multiturn, they can be disabled by setting them to 0.

  5. At your IF2 tile, You can use the functions to read BiSS data and process it into position data.
    #include <CoreC2X.bsp>          //Board Support file for SOMANET Core C2X device
    #include <Drive1000-rev-c4.bsp> //Board Support file for SOMANET Drive module
                                    //(select your board support files according to your device)
    
    // 2. Include the BiSS Service header **biss_service.h** in your app.
    #include <biss_service.h>
    
    // 3.Instantiate the ports for the BiSS.
    port ? qei_hall_port_2 = SOMANET_DRIVE_ENCODER_2_PORT;
    port ? gpio_port_3 = SOMANET_DRIVE_GPIO_D3; // 1-bit port
    
    int main(void)
    {
        par
        {
            on tile[IF2_TILE]:
            {
                // 4. Fill up the BiSS configuration structure.
                PositionFeedbackConfig position_feedback_config;
                position_feedback_config.sensor_type = BISS_SENSOR; // or SSI_SENSOR for SSI
                position_feedback_config.tile_usec   = IF2_TILE_USEC;
                position_feedback_config.biss_config.multiturn_resolution = BISS_MULTITURN_RESOLUTION;
                position_feedback_config.biss_config.singleturn_resolution = BISS_SINGLETURN_RESOLUTION;
                position_feedback_config.biss_config.filling_bits = BISS_FILLING_BITS;
                position_feedback_config.biss_config.crc_poly = BISS_CRC_POLY;
                position_feedback_config.biss_config.clock_frequency = BISS_CLOCK_FREQUENCY;
                position_feedback_config.biss_config.timeout = BISS_TIMEOUT;
                position_feedback_config.biss_config.busy = BISS_BUSY;
                position_feedback_config.biss_config.clock_port_config = BISS_CLOCK_PORT;
                position_feedback_config.biss_config.data_port_number = BISS_DATA_PORT_NUMBER;
                position_feedback_config.biss_config.data_port_signal_type = BISS_DATA_PORT_SIGNAL_TYPE;
    
                // 5. Use the functions to read BiSS data and process it into position data.
                // read BiSS data
                int data[BISS_FRAME_BYTES]; // array of 32 bit bytes to store the data. The size needs to be enough to store all the data bits.
                timer t;
                int biss_clock_low = 0;
                int biss_clock_high = 1;
                int error = read_biss_sensor_data(&gpio_port_3, &qei_hall_port_2, biss_clock_low, biss_clock_high, t, position_feedback_config, data);
                // process data
                int count, position, status;
                { count, position, status } = biss_encoder(data, position_feedback_config);
            }
        }
    
        return 0;
    }
    

API

Definitions

BISS_FRAME_BYTES

Number of 32 bit bytes needed to save the BiSS frame before processing.

It must be large enough to hold: CDS bit + multiturn and singleturn data with filling bits + error and warning bits and the crc (6) 2 bytes should be enough for a sensor up to 55 bits of position data (1 + 55 + 2 + 6 = 64)

BISS_DATA_PORT_BIT

Bit number (0 = rightmost bit) when inputing from a multibit port.

BISS_STATUS_BITS

Number of bits used for status data (usually 2)

Types

PositionFeedbackConfig

Configuration structure of the position feedback service.

Structure Members:

SensorType sensor_type

Select the sensor type.

SensorFunction sensor_function

Select which data to write to shared memory.

SensorPolarity polarity

Encoder polarity.

UsecType tile_usec

Number of clock ticks in a microsecond >

int pole_pairs

Number of pole pairs.

int resolution

Number of ticks per turn.

int offset

Offset (in ticks) added to the absolute multiturn position (count).

Does not affect the electrical angle

int max_ticks

The multiturn position is reset to 0 when reached.

int velocity_compute_period

Velocity compute period in microsecond.

Is also the polling period to write to the shared memory

BISSConfig biss_config

BiSS sensor configuration.

REM_16MTConfig rem_16mt_config

REM 16MT sensor configuration.

REM_14Config rem_14_config

REM 14 configuration.

QEIConfig qei_config

QEI sensor configuration.

HallConfig hall_config

Hall sensor configuration.

GPIOType gpio_config

GPIO configuration.

BISSConfig

Structure type to define the BiSS sensor configuration.

Structure Members:

int multiturn_resolution

Number of bits of multiturn resolution.

int singleturn_resolution

Number of bits of singleturn resolution.

int filling_bits

Number of filling bits between the singleturn data status data.

int crc_poly

CRC polynom in reverse representation: x^0 + x^1 + x^6 is 0b110000.

int clock_frequency

BiSS output clock frequency in kHz, supported frequencies depend on IF2 Tile frequency.

int timeout

Timeout after a BiSS read in microseconds.

int busy

For BiSS maximum number of bits to read before the start bit (= maximum duration of ACK bit).

For SSI processing time before reading in microseconds

BISSClockPortConfig clock_port_config

Configure of the biss clock port (GPIO or hall_enc_select_port)

EncoderPortNumber data_port_number

Configure which port is used for the biss input data.

EncoderPortSignalType data_port_signal_type

Configure of the data port signal type (RS422 (differential) or TTL)

SensorError

Type for Sensor Error.

Enum Values:

SENSOR_NO_ERROR
SENSOR_REM_16MT_WEAK_MAG_FIELD_ERROR
SENSOR_REM_16MT_MT_COUNTER_ERROR
SENSOR_REM_16MT_ST_CORDIC_ERROR
SENSOR_REM_16MT_MT_SPEED_OVERLOW_ERROR
SENSOR_REM_16MT_FILTER_CONFIG_ERROR
SENSOR_REM_16MT_FILTER_SPEED_OVERLOW_ERROR
SENSOR_REM_16MT_UNKNOWN_CMD_ERROR
SENSOR_REM_16MT_CONFIG_ERROR
SENSOR_BISS_ERROR_BIT_ERROR
SENSOR_BISS_WARNING_BIT_ERROR
SENSOR_BISS_ERROR_AND_WARNING_BIT_ERROR
SENSOR_BISS_NO_ACK_BIT_ERROR
SENSOR_BISS_NO_START_BIT_ERROR
SENSOR_CHECKSUM_ERROR
SENSOR_BISS_DATA_LINE_ERROR
SENSOR_QEI_INDEX_LOSING_TICKS
SENSOR_HALL_FAULT
SENSOR_INCREMENTAL_FAULT
SENSOR_POSITION_FAULT
SENSOR_NO_ERROR
SENSOR_REM_16MT_WEAK_MAG_FIELD_ERROR
SENSOR_REM_16MT_MT_COUNTER_ERROR
SENSOR_REM_16MT_ST_CORDIC_ERROR
SENSOR_REM_16MT_MT_SPEED_OVERLOW_ERROR
SENSOR_REM_16MT_FILTER_CONFIG_ERROR
SENSOR_REM_16MT_FILTER_SPEED_OVERLOW_ERROR
SENSOR_REM_16MT_UNKNOWN_CMD_ERROR
SENSOR_REM_16MT_CONFIG_ERROR
SENSOR_BISS_ERROR_BIT_ERROR
SENSOR_BISS_WARNING_BIT_ERROR
SENSOR_BISS_ERROR_AND_WARNING_BIT_ERROR
SENSOR_BISS_NO_ACK_BIT_ERROR
SENSOR_BISS_NO_START_BIT_ERROR
SENSOR_CHECKSUM_ERROR
SENSOR_BISS_DATA_LINE_ERROR
SENSOR_QEI_INDEX_LOSING_TICKS
SENSOR_HALL_FAULT
SENSOR_INCREMENTAL_FAULT
SENSOR_POSITION_FAULT
EncoderPortNumber

Type for Encoder Port.

There are two identical encoder ports which can be used for Hall, QEI and BiSS.

Enum Values:

ENCODER_PORT_1

Encoder connector 1.

ENCODER_PORT_2

Encoder connector 2.

ENCODER_PORT_EXT_D0

Encoder connector 3.

ENCODER_PORT_EXT_D1

Not used anymore.

ENCODER_PORT_EXT_D2

Not used anymore.

ENCODER_PORT_EXT_D3

Not used anymore.

Warning

doxygenstruct: Cannot find struct “QEIHallPort” in doxygen xml output

HallEncSelectPort

Structure for the hall_enc_select port used to select the mode (differential or not) of Hall/qei ports.

Also used for the BiSS clock output

Structure Members:

port p_hall_enc_select

[Nullable] Port to control the signal input circuitry (if applicable in your SOMANET device).

Also used for the BiSS clock output

int hall_enc_select_inverted

Select if the logic is inverted (0 normal, 1 inverted)

SPIPorts

Structure for SPI ports and clock blocks.

Structure Members:

spi_master_class spi_class
port *movable slave_select

Functions

SensorError read_biss_sensor_data(port *biss_clock_port, port *biss_data_port, int biss_clock_low, int biss_clock_high, timer t, PositionFeedbackConfig &position_feedback_config, unsigned int data[])

Read generic BiSS sensor data.

Parameters:
  • biss_clock_port – BiSS/SSI clock port
  • biss_data_port – BiSS/SSI data port
  • biss_clock_low – value of the BiSS clock when low
  • biss_clock_high – value of the BiSS clock when high
  • t – used for the timeout
  • position_feedback_config – Configuration of the BiSS sensor (data lengths, crc polynomial, etc)
  • data – Array to store the read bits, should be large enough to store all the data bits + crc bits
Returns:

error status (No Error, CRC Error, No Ack, No Start Bit)

{ int, unsigned int, SensorError } b biss_encoder(unsigned int data[], PositionFeedbackConfig &position_feedback_config)

Extract position data from a BiSS encoder raw sensor data.

Parameters:
  • data – BiSS raw sensor data
  • position_feedback_config – structure definition for the BiSS encoder data lengths
Returns:

absolute count

Returns:

position in the range [0 - (2^singleturn_resolution - 1)]

Returns:

status (error and warning bits)

unsigned int biss_crc(unsigned int data[], unsigned int data_length, unsigned int crc_poly)

Compute a crc for BiSS data.

Parameters:
  • data – BiSS data
  • data_length – length of data in bits
  • crc_poly – crc polynomial in reverse representation with high exponent omitted: x^0 + x^1 + x^6 is 0b110000
Returns:

inverted crc for BiSS

void biss_crc_correct(unsigned int data[], unsigned int data_length, static const unsigned int frame_bytes, unsigned int crc_received, unsigned int crc_poly)

Try 1-bit error correction for BiSS data.

Parameters:
  • data – BiSS data
  • data_length – length of data in bits
  • frame_bytes – number of 32 bit bytes of data
  • crc_received – crc received with the data
  • crc_poly – crc polynomial in reverse representation: x^0 + x^1 + x^4 is 0b1100