# C Operations
The header ftop.h defines functions that operate on devices generated by the
[allocator](c_allocators.md) functions. These operations include reading values
from inputs and setting outputs.
| Content |
| -------------------------------------------------------------------- |
| [**TXT functions**](#txt-functions) |
| [ ftop_can_set_bitrate](#can_set_bitrate) |
| [ ftop_get_finfo](#get_info) |
| [ ftop_get_values](#get_values) |
| [ ftop_power_down](#power_down) |
| [ ftop_reset](#reset) |
| [ ftop_set_terminator](#set_terminator) |
| [ ftop_set_uid](#set_uid) |
| [ ftop_update_config](#update_config) |
| [ ftop_wait_event](#wait_event) |
| [**Input & Counter functions**](#universal-input--counter-functions) |
| [ ftop_get_distance](#get_distance) |
| [ ftop_get_resistance](#get_resistance) |
| [ ftop_get_state](#get_state) |
| [ ftop_get_temperature](#get_temperature) |
| [ ftop_get_voltage](#get_voltage) |
| [ ftop_zero](#zero) |
| [**Output & Servo functions**](#output--servo-functions) |
| [ ftop_get_pwm](#get_pwm) |
| [ ftop_set_brightness](#set_brightness) |
| [ ftop_set_pwm](#set_pwm) |
| [**Motor & Encoder functions**](#motor--encoder-functions) |
| [ ftop_motor_coast](#motor_coast) |
| [ ftop_motor_get_distance](#motor_get_distance) |
| [ ftop_motor_isruning](#motor_isrunning) |
| [ ftop_motor_set_step_counter](#motor_set_step_counter) |
| [ ftop_motor_set_speed](#motor_set_speed) |
| [ ftop_motor_start_distance](#motor_start_distance) |
| [ ftop_motor_start_speed](#motor_start_speed) |
| [ ftop_motor_start_sync_distance](#motor_start_sync_distance) |
| [ ftop_motor_stop](#motor_stop) |
| [ ftop_motor_stop_sync](#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](devices.md#ultrasonic) 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](devices.md#resistor) and [Thermistor](devices.md#ntc-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](devices.md#ntc-thermistor) 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](devices.md#voltmeter).
| Type | Paremeter | Description |
| ------- | ------------ | ---------------------- |
| *in* | **device** | pointer to voltmeter |
Return:
voltage in *mV*
### void ftop_zero(void *device)
Resets a [counter](devices.md#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](devices.md#output) or [servos](devices.md#servo).
| 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](devices.md#output).
| 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](devices.md#output) or [servos](devices.md#servo).
| 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](devices.md#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](devices.md#encoder).
| Type | Paremeter | Description |
| ------- | ------------ | ---------------------- |
| *in* | **device** | pointer to encoder |
Return:
covered distance
### bool ftop_motor_isrunning(void *device)
Returns whether or not the [encoder motor](devices.md#encoder) 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](devices.md#encoder).
| 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](devices.md#motors). 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](devices.md#encoder) 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](devices.md#motors) 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](devices.md#encoder) 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](#void-ftop_motor_set_speedvoid-device-int-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|