ev3c_sensor

These functions are for reading sensor values of the EV3 brick.  The flow is to search first for all connected sensors with ev3_load_sensors.  This list can then be searched with ev3_search_sensor_by_name and ev3_search_sensor_by_port (or by hand).  To use a sensor, it has to be opened with ev3_open_sensor.  The sensor values are stored in the ev3_sensor struct (variables bin_data and val_data).  However they need to be updated by hand calling ev3_update_sensor_bin or ev3_update_sensor_val.  In the very end the sensors should be closed using ev3_close_sensor or using ev3_delete_sensors, which cleans the list and closes all sensors if open.

Keep in mind, that some sensors are not identified automaticly (like the NXT sound sensor).  These device need to be set to the right driver using <ev3_driver_sensor>.

Summary
ev3c_sensorThese functions are for reading sensor values of the EV3 brick.
Enumerations
ev3_bin_data_format_enumthe format of the binary raw data of the sensors.
Types
ev3_sensorA struct for every loaded sensor.
Functions
ev3_load_sensors
ev3_delete_sensorsDeletes the linked list of available sensors.
ev3_open_sensorOpens the sensor to be used.
ev3_search_sensor_by_nameSearches for a sensor in the linked list identified with the name.
ev3_search_sensor_by_portSearches for a sensor in the linked list identified with the port.
ev3_close_sensorCloses the sensor.
ev3_update_sensor_binUpdates the raw values of the sensor.
ev3_update_sensor_valUpdates the formated values of the sensor.
ev3_mode_sensorSets the mode of the sensor, e.g.
ev3_mode_sensor_by_nameSets the mode of the sensor, e.g.

Enumerations

ev3_bin_data_format_enum

the format of the binary raw data of the sensors.

Values

U8unsigned, one byte length
S8signed, one byte length
U16unsigned, two bytes length
S16signed, two bytes length
S16_BEsigned, two beytes length, Big Endian
S32signed, four bytes length
FLOATfloat

Types

ev3_sensor

A struct for every loaded sensor.

Variables

driver_name(ev3_string) Name of the driver driver
port(int32) Port (1..4) of the EV3 brick
sensor_nr(int32) internal, incrementing counter of the sensors in ev3dev
bin_fd(int32) file descriptor for reading the raw data for the sensor.  -1 if not set or if an error occured.
val_fd(array of int32) 8 file descriptors for reading the formated data of the sensor.
bin_data(array of union) the read raw data of the sensor. data_count values are stored.  Use ev3_update_sensor_bin to update the data before using it.  The union consists of u8 (uint8), s8 (int8), u16 (uint16), s16 (int16), s16_be (int16 big endian), s32 (int32) and f (float).  Which you should use depends on bin_data_format.  However s32 should always give you useful results (except for f and s16_be).
val_data(array of union) the read formated data of the sensor. data_count values are stored.  Use ev3_update_sensor_val to update the data before using it.  The union consits only of s32 (int32) and f (float). f makes only sense to use, if bin_data_format is FLOAT.
units(ev3_string) the units used by the values, like V (Volt), pct (Percent) or u/m² (unicors per square meter).
decimals(int32) the decimal shift you should consider while interpretating the formated values, especially for the units to make sense.  E.g. if the formated value is 667, units “pct” and decimals 1, the value would be 66.7% .
poll_ms(int32) the time in ms, when the sensor is reread for I2C devices.
modes(array of ev3_string) the supported modes of the sensor.
mode_count(int32) the number of supported modes of the sensor.  However some modes may not be useable anyway.  Have a look at the documentation of the sensor type for more information.
mode(int32) the choosen mode.
next(pointer of ev3_sensor) next element in the linked list.  NULL for the last element.

Functions

ev3_load_sensors

ev3_sensor_ptr ev3_load_sensors(void)

Returns

*ev3_sensorreturns a linked list of all available sensors.

ev3_delete_sensors

void ev3_delete_sensors(ev3_sensor_ptr sensors)

Deletes the linked list of available sensors.

Parameters

sensors(pointer of ev3_sensor) list to delete

ev3_open_sensor

ev3_sensor_ptr ev3_open_sensor(ev3_sensor_ptr sensor)

Opens the sensor to be used.  If called twice nothing happens.

Parameters

sensor(pointer of ev3_sensor) the sensor to be opened.  You can just iterate of all sensors returns by ev3_load_sensors or you search for a specific sensor with ev3_search_sensor_by_name or ev3_search_sensor_by_port and open just this one.

Returns

*ev3_sensorreturns the parameter.  Useful if you opened the sensor with ev3_open_sensor(ev3_search_sensor_by_name(...)).

ev3_search_sensor_by_name

ev3_sensor_ptr ev3_search_sensor_by_name(ev3_sensor_ptr sensors,
char *name,
int32_t not_ready)

Searches for a sensor in the linked list identified with the name.  It may be, that you connected two sensors with the same name (e.g. two ev3-touch-sensors).  In that case you can specify to search only for not yet opened sensors.

Parameters

sensors(pointer of ev3_sensor) linked list of sensors created by ev3_load_sensors.
name(char*) name to search for.
not_ready(int32) specifies, whether an already opened sensor should be returned or not.  If not_ready is 1 only a not yet opened sensor will be returned.

Returns

*ev3_sensorthe found sensor.  May be NULL if nothing is found.

ev3_search_sensor_by_port

ev3_sensor_ptr ev3_search_sensor_by_port(ev3_sensor_ptr sensors,
int32_t port)

Searches for a sensor in the linked list identified with the port.  The ports are labeled like on the EV3 brick starting with 1.

Parameters

sensors(pointer of ev3_sensor) linked list of sensors created by ev3_load_sensors.
port(int32) Port to search for.

Returns

*ev3_sensorthe found sensor.  May be NULL if nothing is found.

ev3_close_sensor

void ev3_close_sensor(ev3_sensor_ptr sensor)

Closes the sensor.  The pointer is not freed.  The values are not reseted or invalid.  You “just” can’t use ev3_update_sensor_bin and ev3_update_sensor_val anymore.

Parameters

sensor(point of ev3_sensor) sensor to close.

ev3_update_sensor_bin

void ev3_update_sensor_bin(ev3_sensor_ptr sensor)

Updates the raw values of the sensor.  Faster than ev3_update_sensor_val, but the values may not be useful.  Use it only if you ran into serious speed problems.  The sensor needs to be opened with ev3_open_sensor first.

Parameters

sensor(pointer of ev3_sensor) sensor to update it’s raw values stored in bin_data.

ev3_update_sensor_val

void ev3_update_sensor_val(ev3_sensor_ptr sensor)

Updates the formated values of the sensor.  Slower than ev3_update_sensor_bin, but the values are much more useful.  Furthermore if I say “slow” I mean around 50µs, which is in fact quite fast (but still slower than ev3_update_sensor_bin).  The sensor needs to be opened with ev3_open_sensor first.

Parameters

sensor(pointer of ev3_sensor) sensor to update it’s formated values stored in val_data.

ev3_mode_sensor

ev3_sensor_ptr ev3_mode_sensor(ev3_sensor_ptr sensor,
int32_t mode)

Sets the mode of the sensor, e.g.  COL-COLOR on the color sensor to get the color of the underground

Parameters

sensor(pointer of ev3_sensor) sensor to change it’s mode
mode(int32) mode to be set to.  It refers to the number in the array modes in sensor.  E.g.  COL-COLOUR would be 2.

Returns

*ev3_sensorthe same pointer as passed as argument.  Useful for such call chains as ev3_open( ev3_mode_sensor( sensor, 1 ) );

ev3_mode_sensor_by_name

ev3_sensor_ptr ev3_mode_sensor_by_name(ev3_sensor_ptr sensor,
char *mode)

Sets the mode of the sensor, e.g.  “COL-COLOR” on the color sensor to get the color of the underground using the name of the mode.  Slower, but more easy to use than ev3_mode_sensor, which makes sense espcecially if you change the mode of a sensor quite often (e.g. using the IR sensor for IR control and distance measurment at the same time).  If such a mode doesn’t exist, nothing happens and no mode is changed.

Parameters

sensor(pointer of ev3_sensor) sensor to change it’s mode
mode(char*) mode to be set to.  It refers to the name from in the array modes in sensor, e.g.  “COL-COLOUR”.

Returns

*ev3_sensorthe same pointer as passed as argument.  Useful for such call chains as ev3_open( ev3_mode_sensor( sensor, 1 ) );
ev3_sensor_ptr ev3_load_sensors(void)
void ev3_delete_sensors(ev3_sensor_ptr sensors)
Deletes the linked list of available sensors.
ev3_sensor_ptr ev3_open_sensor(ev3_sensor_ptr sensor)
Opens the sensor to be used.
ev3_sensor_ptr ev3_search_sensor_by_name(ev3_sensor_ptr sensors,
char *name,
int32_t not_ready)
Searches for a sensor in the linked list identified with the name.
ev3_sensor_ptr ev3_search_sensor_by_port(ev3_sensor_ptr sensors,
int32_t port)
Searches for a sensor in the linked list identified with the port.
void ev3_close_sensor(ev3_sensor_ptr sensor)
Closes the sensor.
void ev3_update_sensor_bin(ev3_sensor_ptr sensor)
Updates the raw values of the sensor.
void ev3_update_sensor_val(ev3_sensor_ptr sensor)
Updates the formated values of the sensor.
ev3_sensor_ptr ev3_mode_sensor(ev3_sensor_ptr sensor,
int32_t mode)
Sets the mode of the sensor, e.g.
ev3_sensor_ptr ev3_mode_sensor_by_name(ev3_sensor_ptr sensor,
char *mode)
Sets the mode of the sensor, e.g.
A struct for every loaded sensor.
type used for all strings used from the driver lile mode names, commands and similar.
Close