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_identifier 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_sensor_identifiera number for every (yet) supported sensor in ev3dev.
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_identifierSearches for a sensor in the linked list identified with the identifier.
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_sensor_identifier

a number for every (yet) supported sensor in ev3dev.  For more information have a look at the ev3dev wiki.

Values

EV3_ANALOG_XXEV3_ANALOG_XX
NXT_ANALOGNXT_ANALOG
HT_NXT_COLORHT_NXT_COLOR
HT_NXT_ANGLEHT_NXT_ANGLE
HT_NXT_ACCELHT_NXT_ACCEL
HT_NXT_BAROMETRICHT_NXT_BAROMETRIC
HT_NXT_COLOR_V2HT_NXT_COLOR_V2
HT_NXT_EOPDHT_NXT_EOPD
HT_NXT_FORCEHT_NXT_FORCE
HT_NXT_GYROHT_NXT_GYRO
HT_NXT_IR_LINKHT_NXT_IR_LINK
HT_NXT_IR_RECEIVERHT_NXT_IR_RECEIVER
HT_NXT_PIRHT_NXT_PIR
HT_NXT_COMPASSHT_NXT_COMPASS
HT_NXT_MAGHT_NXT_MAG
HT_NXT_IR_SEEK_V2HT_NXT_IR_SEEK_V2
HT_NXT_SMUXHT_NXT_SMUX
HT_SUPER_PROHT_SUPER_PRO
LEGO_EV3_UART_30LEGO_EV3_UART_30
LEGO_EV3_UART_32LEGO_EV3_UART_32
LEGO_EV3_UART_29LEGO_EV3_UART_29
LEGO_EV3_TOUCHLEGO_EV3_TOUCH
LEGO_EV3_UART_33LEGO_EV3_UART_33
WEDO_HUBWEDO_HUB
WEDO_MOTIONWEDO_MOTION
WEDO_TILTWEDO_TILT
LEGO_POWER_STORAGELEGO_POWER_STORAGE
TMP275TMP275
LEGO_NXT_TOUCHLEGO_NXT_TOUCH
LEGO_NXT_LIGHTLEGO_NXT_LIGHT
LEGO_NXT_SOUNDLEGO_NXT_SOUND
LEGO_NXT_USLEGO_NXT_US
MI_XG1300LMI_XG1300L
MS_ABSOLUTE_IMUMS_ABSOLUTE_IMU
MS_ANGLEMS_ANGLE
MS_EV3_SMUXMS_EV3_SMUX
MS_LIGHT_ARRAYMS_LIGHT_ARRAY
MS_LINE_LEADERMS_LINE_LEADER
MS_8CH_SERVOMS_8CH_SERVO
PCF8574PCF8574
PCF8591PCF8591
DS1307DS1307
MS_NXT_TOUCH_MUXMS_NXT_TOUCH_MUX UNKNOWN_SENSOR- UNKNOWN_SENSOR

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_identifier(ev3_sensor_identifier) Identifier of the 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_identifier 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_identifier(...)).

ev3_search_sensor_by_identifier

ev3_sensor_ptr ev3_search_sensor_by_identifier(
   ev3_sensor_ptr sensors,
   enum ev3_sensor_identifier identifier,
   int32_t not_ready
)

Searches for a sensor in the linked list identified with the identifier.  It may be, that you connected two sensors with the same identifier (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.
identifier(ev3_sensor_identifier) Identifier 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_identifier(
   ev3_sensor_ptr sensors,
   enum ev3_sensor_identifier identifier,
   int32_t not_ready
)
Searches for a sensor in the linked list identified with the identifier.
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.
a number for every (yet) supported sensor in ev3dev.
Close