c_operations

<style> table { width: 100%; } table tr td a { display: block !important; height: 100% !important; width: 100% !important; padding: 7px !important; padding-left: 14px !important; padding-right: 14px !important; margin: -7px !important; margin-left: -14px !important; margin-right: -14px !important; color: inherit !important; } @media (prefers-color-scheme: dark) { .type { color: FireBrick; font-style: italic; } } @media (prefers-color-scheme: light) { .type { color: FireBrick; font-style: italic; } } </style>

C Operations

The header ftop.h defines functions that operate on devices generated by the allocator functions. These operations include reading values from inputs and setting outputs.

Content
TXT functions
ftop_can_set_bitrate
ftop_get_finfo
ftop_get_values
ftop_power_down
ftop_reset
ftop_set_terminator
ftop_set_uid
ftop_update_config
ftop_wait_event
Input & Counter functions
ftop_get_distance
ftop_get_resistance
ftop_get_state
ftop_get_temperature
ftop_get_voltage
ftop_zero
Output & Servo functions
ftop_get_pwm
ftop_set_brightness
ftop_set_pwm
Motor & Encoder functions
ftop_motor_coast
ftop_motor_get_distance
ftop_motor_isruning
ftop_motor_set_step_counter
ftop_motor_set_speed
ftop_motor_start_distance
ftop_motor_start_speed
ftop_motor_start_sync_distance
ftop_motor_stop
ftop_motor_stop_sync

TXT functions

void ftop_can_set_bitrate(void *device, int speed)

Sets a new CAN bitrate.

Type	Paremeter	Description
in	device	pointer to TXT object.
in	speed	new CAN bitrate (in Hz)

int ftop_get_finfo(void *device, ftfaults *finfo)

Returns TXT's current fault information.

Type	Paremeter	Description
in	device	pointer to TXT object
out	finfo	pointer to ft_faults struct

Return:
        status code (always 0)

int ftop_get_values(void *device, int values[FT_MAX_INPUTS + FT_MAX_COUNTERS])

Returns an array with the current values (state for switch and digital, distance for ultrasonic, raw voltage for resistor/thermistor) for the all inputs and the current counts for all counters (via out parameter).

Type	Paremeter	Description
in	device	pointer to TXT object.
out	finfo	pointer to int array with FT_MAX_INPUTS + FT_MAX_COUNTERS fields (12)

Return:
        status code (always 0)

void ftop_power_down(void *device)

Powers down the M4.

Type	Paremeter	Description
in	device	pointer to TXT object

void ftop_reset(void *device)

As of now, this function does nothing.

Type	Paremeter	Description
in	device	pointer to TXT object

void ftop_set_terminator(void *device, int mode)

Toggels whether or not to use a termitator for FDCAN.
mode = 0 disabels the terminator, mode = 1 enabels it.

Type	Paremeter	Description
in	device	pointer to TXT object
in	mode	new mode

void ftop_set_uid(void *device, uint32_t uid)

Sets a new uid for the TXT.

Type	Paremeter	Description
in	device	pointer to TXT object
in	uid	new uid

void ftop_update_config(void *device)

Updates the TXT's input/output configuration. This function MUST be called after allocating new sensors and actuators for them to become usable. Since this functions requires communication with the M4, the update is not in effect immediatly after the function returns, so a sleep might be used to make sure the peripheral is usuable. For updating the master TXT, 10 ms is sufficient, updating slave TXT takes up to 70 ms.

Type	Paremeter	Description
in	device	pointer to TXT object

int ftop_wait_event(void *device, uint32_t emask)

Blocks the thread and listens on one or more TXT events. The event types are specified using a bit mask. The thread is blocked until at least one of the events was triggered, returning a bit mask containing the detected events from the original bit mask.

Type	Paremeter	Description
in	device	pointer to TXT object
in	emask	bitmask of desired events

Return:
        event mask

Universal Input & Counter functions

int ftop_get_distance(void *device)

Returns the current distance from a ultrasonic distance sensor in cm.

Type	Paremeter	Description
in	device	pointer to ultrasonic object

Return:
        distance in cm

int ftop_get_resistance(void *device)

Calulates and returns the resistance for Resistor and Thermistor devices.

Type	Paremeter	Description
in	device	pointer to resistor

Return:
        resistance in Ω

int ftop_get_state(void *device)

Returns the 'state' for universal inputs and counters. For digital devices, the state is returned, for analog devices, the analog value is returned and for counters, the count is returned.

Type	Paremeter	Description
in	device	pointer to device

Return:
        state for digital devices, value for analog devices, count for counters.

int ftop_get_temperature(void *device)

Calculates and returns the temperature in °C for the fischertechnik 1,5 kΩ NTC using the beta-model.

Note: This calculation provides correct results for THIS NTC only. For different thermistors, the user must implement their own function to calculate the temperature from the resistance.

Type	Paremeter	Description
in	device	pointer to thermistor

Return:
        temperature in K

int ftop_get_voltage(void *device)

Returns the voltage for voltmeter devices.

Type	Paremeter	Description
in	device	pointer to voltmeter

Return:
        voltage in mV

void ftop_zero(void *device)

Resets a counter. This function can be called on a counter object or on an encoder motor object. In the latter case the counter associated with the encoder is resetted.

Note: This function requires communication with the M4, therefore the reset is not in affect immediatly after the function is returned but after a brief delay.

Type	Paremeter	Description
in	device	pointer to counter or encoder

Output & Servo functions

unsigned int ftop_get_pwm(void *device);

Returns current PWM setting for outputs or servos.

Type	Paremeter	Description
in	device	pointer to output or servo

Return:
        PWM value [0, 512]

void ftop_set_brightness(void *device, int value)

Sets the PWM value (brightness) for outputs.

Type	Paremeter	Description
in	device	pointer to output
in	value	new PWM value [0, 512]

void ftop_set_pwm(void *device, int value)

Sets the PWM value for outputs or servos.

Type	Paremeter	Description
in	device	Pointer to output or servo
in	value	new PWM value [0, 512]

Motor & Encoder functions

void ftop_motor_coast(void *device, int mask)

Sets motors in "coast mode". The motors are selected using the bit mask.

Note: The motors are NOT stopped immediatly! The M4 will stop them in its next update cycle.

Type	Paremeter	Description
in	device	pointer to motor or encoder
in	mask	bit mask of selected motors

int ftop_motor_get_distance(void *device)

Gets the distance covered by the encoder motor.

Type	Paremeter	Description
in	device	pointer to encoder

Return:
        covered distance

bool ftop_motor_isrunning(void *device)

Returns whether or not the encoder motor is currently running.

Note: This does not mean the motor's cureent speed is non-zero! It checks whether or not the last motor command has been excecuted or not.

Type	Paremeter	Description
in	device	pointer to encoder

Return:
        motor's state

void ftop_motor_set_step_counter(void *device, void *counter)

Sets a new counter for an encoder motor.

Type	Paremeter	Description
in	device	pointer to encoder
in	counter	pointer to counter

void ftop_motor_set_speed(void *device, int speed)

Sets a new speed for a motor. The speed is in the range [-512, 512]. This function does not start the motor!

Type	Paremeter	Description
in	device	pointer to motor or encoder
in	speed	new speed [-512, 512]

void ftop_motor_start_distance(void *device, int distance, void *device2)

Immediatly starts the encoder motor to run for the given distance. If a second encoder has been passed as argument, both motors run syncronized. Otherwise, NULL is passed as 3rd argument. Both motors run at their own speed that was set prior to this function call.

Type	Paremeter	Description
in	device	pointer to encoder
in	distance	distance in steps
in	device2	pointer to 2nd encoder or NULL

void ftop_motor_start_speed(void *device, int speed)

Immediatly starts the motor at the given speed.

Type	Paremeter	Description
in	device	pointer to motor or encoder
in	speed	new speed [-512, 512]

void ftop_motor_start_sync_distance(void *device, int distance, int mask)

Immediatly starts all motors selected by the bit mask. They are syncronized to run for the given distance, but each motor runs at its own speed that was set using ftop_motor_set_speed.

Type	Paremeter	Description
in	device	pointer to motor or encoder
in	distance	distance in steps
in	mask	bit mask of selected motors

void ftop_motor_stop(void *device)

Immediatly stops motor or encoder.

Type	Paremeter	Description
in	device	pointer to encoder

void ftop_motor_stop_sync(void *device, int mask)

Immediatly stop all motors and encoders specified by the bit mask.

Type	Paremeter	Description
in	device	pointer to motor or encoder
in	mask	bit mask of selected motors