This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
en:libschsat-py [2018/10/10 11:59] golikov |
en:libschsat-py [2020/03/25 16:28] (current) |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== Python interface ====== | + | ====== Python Function Libraries ====== |
- | Starting with version 1.02, the standard library includes support for the [[https://www.python.org|Python]] programming language. If you use this version of the library or more recent versions, then you can access the interface functions of the standard library using one of the most popular programming languages. ((The standard library is implemented in the low-level programming language С.)) | + | **Description of Python Function Libraries** |
- | ===== Fast start ===== | + | Functions described below are used for interaction with Orbicraft construction set subsystems by programs written in Python version 2.7. |
- | In order to create a simple Python project | + | **Quick Start** |
- | - Put your Python code in a separate file with the extension ''.py'' ((The following reserved file names are not allowed: ''main.py'' and ''schsat.py''.)) | + | Here is what you need to create a bare-bones Python project: |
- | - Implement a function named ''control'' in Python ((The function '' control () '' is the entry point to your Python code, look at it as a function ''main()''.)) | + | |
- | Here is an example of a simple Python project: | + | 1. Place your Python into a separate file with the ''.py'' extension (Do not use the following reserved filenames: ''main.py'' and ''schsat.py''). |
+ | |||
+ | 2. Implement a function named ''control'' in Python (The ''control()'' function is an entry point into your Python code. View it in the same manner as the ''main()'' function). | ||
+ | |||
+ | Example of a simple project in Python | ||
<file python hello.py> | <file python hello.py> | ||
Line 18: | Line 21: | ||
</file> | </file> | ||
- | ===== Interface Functions ===== | + | **Introduction** |
- | + | ||
- | In describing the interface functions, we will indicate: | + | |
- | * function name (function name is unique) | + | Our function descriptions will include: |
- | * list of arguments for this function | + | |
- | * list of values returned by the function | + | |
+ | * Function name (this name is unique) | ||
+ | * A list of arguments accepted by the function | ||
+ | * A list of values returned by the function. | ||
Example | Example | ||
Line 31: | Line 33: | ||
hyro_request_reset(num) -> err | hyro_request_reset(num) -> err | ||
- | In the example above, the interface named ''hyro_request_reset'' is shown. ''hyro_request_reset''is the name of the Python function. The function takes one argument ''num'' (sensor number) and returns a single value -- ''err'' (error code). | + | The preceding example describes an interface named ''hyro_request_reset'' – this is the name of a Python function; the function accepts a single argument ''num'' (sensor number) and returns a single value ''err'' (error code). |
- | Most interface functions expect that the first argument is the device number (number of sensor or number of actuating mechanism). Usually, the device number is a number from ''0'' to ''3''. Also, most interface functions return the value of the called function's execution status (return an error code). In the example above, this is marked as a pair of characters --> ''err''. | + | Most functions expect ''device ID'' (sensor number or the number of a particular actuator of given type) as their first argument. Devices are commonly numbered 0 to 3. Furthermore, most function return the execution status of the function being invoked (the error code). The foregoing example denotes this fact with the symbol pair -> ''err''. |
- | When using interface functions, it is important to analyze the returned error code (the value of ''err''). If the called function was completed without error, it returns zero ''(0)''. Otherwise, it will return a non-zero value. Below is ann example of processing the value returned by the function: | + | When using functions it is important to analyze the return code (the ''err'' value). When the function being called completes without an error it returns zero (0), otherwise a nonzero value is returned. Sample handling of the return value of the function: |
<code python> | <code python> | ||
err = hyro_request_reset(0) | err = hyro_request_reset(0) | ||
if err: | if err: | ||
- | print 'Error!' | + | print 'An error occurred!' |
</code> | </code> | ||
- | Interface functions often have functions called ''interface_request_reset'', ''interface_get_state'', ''interface_turn_on()'' and ''interface_turn_off'', where ''interface'' is the name of the interface. | + | There are common functions named ''interface_request_reset'', ''interface_get_state'', ''interface_turn_on()'' and ''interface_turn_off'', where ''interface'' , where interface is the interface name. |
- | These functions are generally used as follows (Example for the ''hyro'' interface): | + | These functions are generally used as follows. This example is for the interface named ''hyro'': |
<code python> | <code python> | ||
hyro_request_reset(num) # reset (initialize) the interface | hyro_request_reset(num) # reset (initialize) the interface | ||
- | sleep(1.0/2) # wait a little, for example, 1/2 second | + | sleep(1.0/2) # Make a short delay – half a second for example |
- | hyro_turn_on(num) # enable (activate) the interface | + | hyro_turn_on(num) # Turn on (activate) the interface |
- | ready = hyro_get_state(num) # Verify the interface is ready | + | ready = hyro_get_state(num) # Check whether the interface is ready |
if ready: | if ready: | ||
- | # do something useful, for example, take readings | + | # Do something sensible e.g. capture readings |
(err, x, y, z) = hyro_request_raw(num) | (err, x, y, z) = hyro_request_raw(num) | ||
if not err: | if not err: | ||
print 'x=%d y=%d z=%d' % (x, y, z) | print 'x=%d y=%d z=%d' % (x, y, z) | ||
- | hyro_turn_off(num) # be sure to turn off the interface! | + | hyro_turn_off(num) # Never forget to turn off the interface! |
</code> | </code> | ||
+ | **Subsystem Functions** | ||
- | ==== Interface Accelerometer ==== | + | Functions working with subsystems are described below. |
- | accelerometer_get_state(num) -> ready | + | **Orbiter Power System (OPS)** |
- | [TBD] | + | These functions check the state of OPS virtual battery. They take no arguments. All functions return a single-precision floating-point value. |
- | accelerometer_request_raw(num) -> (err, x, y, z) | + | <code python>battery_get_charge() -> value</code> |
+ | The ''battery_get_charge'' returns the remaining capacity of the battery in ampere-hours. | ||
- | [TBD] | + | <code python>battery_get_charging_current() -> value</code> |
+ | The ''battery_get_charging_current'' function returns the instantaneous battery charge current value in milliamperes. | ||
+ | <code python>battery_get_discharging_current() -> value</code> | ||
+ | The ''battery_get_discharging_current'' function returns the instantaneous battery discharge current value in milliamperes. | ||
- | accelerometer_request_reset(num) -> err | + | **Magnetometer** |
- | [TBD] | + | The ''num'' argument is the magnetometer ID (within the range of 0 to 3). |
- | accelerometer_turn_off(num) -> err | + | magnetometer_get_state(num) -> ready |
- | [TBD] | + | The ''magnetometer_get_state'' function returns a readiness flag for the magnetometer ''num''. |
- | accelerometer_turn_on(num) -> err | + | magnetometer_request_raw(num) -> (err, x, y, z) |
- | [TBD] | + | The ''magnetometer_request_raw'' function returns a list of values: ''err'' is the error code; ''x, y, z'' are current readings of the magnetometer ''num''. |
- | ==== Interface Battery ==== | + | magnetometer_request_reset(num) -> err |
+ | The ''magnetometer_request_reset'' function resets the magnetometer ''num''. | ||
- | These interface functions allow you to determine the state of the virtual battery ([[power_subsys|PSS]]). These functions do not take any arguments. Each of the functions returns a parameter as a single-precision floating-point number. | + | magnetometer_turn_off(num) -> err |
- | battery_get_charge() -> value | + | The ''magnetometer_turn_off'' turns off the magnetometer ''num''. |
- | The function ''battery_get_charge'' returns the current battery charge value expressed in ampere-hours. | + | magnetometer_turn_on(num) -> err |
- | battery_get_charging_current() -> value | + | The ''magnetometer_turn_on function'' turns on (activates) the magnetometer ''num''. |
- | The function ''battery_get_charging_current'' returns the current value of the charge current in milliamperes. | + | **Angular Velocity Sensor (AVS)** |
- | battery_get_discharging_current() -> value | + | These functions are for interfacing with the angular velocity sensor (AVS). The ''num'' argument identifies the sensor (within the range of 0 to 3). |
+ | <code python>hyro_get_state(num) -> ready</code> | ||
+ | The ''hyro_get_state'' returns the device readiness flag: 1 – the sensor is ready; 0 – not ready. | ||
+ | <code python>hyro_request_raw(num) -> (err, x, y, z)</code> | ||
+ | The ''hyro_request_raw'' function returns a list consisting of error code ''err'' and current AVS readings: ''x, y, z''. | ||
+ | <code python>hyro_request_reset(num) -> err</code> | ||
+ | The ''hyro_request_reset'' function resets the sensor ''num''. | ||
+ | <code python>hyro_turn_off(num) -> err</code> | ||
+ | The ''hyro_turn_off'' turns off the sensor ''num''. | ||
+ | <code python>hyro_turn_on(num) -> err</code> | ||
+ | The ''hyro_turn_on'' function turns on (activates) the sensor ''num''. | ||
- | The function ''battery_get_discharging_current'' returns the current value of the discharge current in milliamperes. | + | **Solar Sensor** |
- | ==== Interface Camera ==== | + | The ''num'' argument identifies the sensor (within the range of 0 to 7). |
- | This set of interface functions is designed to work with a camera. | + | sun_sensor_get_state(num) -> ready |
- | camera_get_state() -> ready | + | The ''sun_sensor_get_state'' function returns the readiness flag for the solar sensor identified with ''num'': 1 – the sensor is ready; 0 – not ready. |
- | The function ''camera_get_state'' returns the device ready flag: ''1'' - ready, ''0'' - not ready. | + | sun_sensor_request_maxraw(num) -> (err, value) |
- | camera_take_photo(frame) -> err | + | The ''sun_sensor_request_maxraw'' function returns a list where ''err'' is the error code and ''value'' is the maximum reading of the solar sensor ''num''. |
- | The function ''camera_take_photo'' takes a photo with the number specified with the argument ''frame''. Usually, you number the pictures with numbers from ''0'' to ''9''. The function returns ''0'' if the action is successful, otherwise the value is non-zero. | + | sun_sensor_request_raw(num) -> (err, value, value) |
- | camera_turn_off() -> err | + | The ''sun_sensor_request_raw'' function returns a list where ''err'' is the error code and ''value'' is the current reading of the solar sensor ''num''. |
- | The function ''camera_turn_off'' turns off the device. | + | sun_sensor_request_reset(num) -> err |
- | camera_turn_on() -> err | + | The ''sun_sensor_request_reset'' function resets the sensor ''num''. |
- | The function ''camera_turn_on'' turns on (activates) the device. | + | sun_sensor_set_calibrate(num, value) -> err |
- | ==== Interface Coil ==== | + | The ''sun_sensor_set_calibrate'' function calibrates a sensor (for the sensor identified with ''num'', the mode is set into value). **This function is currently unused.** |
- | coil_get_state(num) -> ready | + | sun_sensor_set_minvalue(num, value) -> err |
- | [TBD] | + | The ''sun_sensor_set_minvalue'' function **is not used.** |
- | coil_request_reset(num) -> err | + | sun_sensor_turn_off(num) -> err |
- | [TBD] | + | The ''sun_sensor_turn_off'' function turns off the solar sensor ''num''. |
- | coil_set_value(num, value) -> (err, value) | + | sun_sensor_turn_on(num) -> err |
- | [TBD] | + | The ''sun_sensor_turn_on'' function turns on (activates) the solar sensor ''num''. |
- | coil_turn_off(uint16_t num) -> err | + | sun_sensors_angle(value, value, value) -> value |
- | [TBD] | + | The ''sun_sensors_angle'' function performs no control operations. It is a computational utility function that returns a double-precision floating-point value. |
- | coil_turn_on(num) -> err | + | **Reaction Wheel** |
- | [TBD] | + | The ''num'' argument is the reaction wheel ID (within the range of 0 to 3). |
- | ==== Interface Light_sensor ==== | + | motor_get_state(num) -> ready |
- | light_sensor_get_state(num) -> ready | + | The ''motor_get_state'' function returns the readiness flag for the reaction wheel identified with ''num'': 1 – ready; 0 – not ready. |
- | + | ||
- | [TBD] | + | |
- | + | ||
- | light_sensor_request_maxraw(num) -> (err, value) | + | |
- | + | ||
- | [TBD] | + | |
- | + | ||
- | light_sensor_request_raw(num) -> (err, value) | + | |
- | + | ||
- | [TBD] | + | |
- | + | ||
- | light_sensor_request_reset(num) -> err | + | |
- | + | ||
- | [TBD] | + | |
- | + | ||
- | light_sensor_set_calibrate(num, value) -> err | + | |
- | + | ||
- | [TBD] | + | |
- | + | ||
- | light_sensor_set_minvalue(num, value) -> err | + | |
- | + | ||
- | [TBD] | + | |
- | + | ||
- | light_sensor_turn_off(num) -> err | + | |
- | + | ||
- | [TBD] | + | |
- | + | ||
- | light_sensor_turn_on(num) -> err | + | |
- | + | ||
- | + | ||
- | ==== Interface Hyro ==== | + | |
- | + | ||
- | These interface functions are used to work with the angular velocity sensor ([[w_subsys|AVS]]). The argument ''num'' is a sensor number (it can take values from ''0'' to ''3''). | + | |
- | + | ||
- | hyro_get_state(num) -> ready | + | |
- | + | ||
- | The function ''hyro_get_state'' returns the device ready flag: ''1'' - ready; ''0'' - not ready. | + | |
- | + | ||
- | hyro_request_raw(num) -> (err, x, y, z) | + | |
- | + | ||
- | The function ''hyro_request_raw'' returns a list: error code ''err'' and the current AVS readings: ''x'', ''y'', ''z''. | + | |
- | + | ||
- | hyro_request_reset(num) -> err | + | |
- | + | ||
- | The function ''hyro_request_reset'' performs reset of the sensor number ''num''. | + | |
- | + | ||
- | hyro_turn_off(num) -> err | + | |
- | + | ||
- | The function ''hyro_turn_off'' turns off the sensor number ''num'' . | + | |
- | + | ||
- | hyro_turn_on(num) -> err | + | |
- | + | ||
- | The function ''hyro_turn_on'' turns on (activates) a sensor number ''num''. | + | |
- | + | ||
- | ==== Interface Magnetometer ==== | + | |
- | + | ||
- | These interface functions are designed to work with a [[mag_subsys|magnetometer]]. The argument ''num'' is the number of the magnetometer (it can take values from ''0'' to ''3''). | + | |
- | + | ||
- | magnetometer_get_state(num) -> ready | + | |
- | + | ||
- | The function ''magnetometer_get_state'' returns the readiness flag of the magnetometer number ''num''. | + | |
- | + | ||
- | magnetometer_request_raw(num) -> (err, x, y, z) | + | |
- | + | ||
- | The function ''magnetometer_request_raw'' returns a list of values: ''err'' - error code; ''x'', ''y'', ''z'' are the current readings of the magnetometer number ''num''. | + | |
- | + | ||
- | magnetometer_request_reset(num) -> err | + | |
- | The function ''magnetometer_request_reset'' performs reset of the magnetometer number ''num''. | + | |
- | + | ||
- | magnetometer_turn_off(num) -> err | + | |
- | + | ||
- | The function ''magnetometer_turn_off'' turns off the magnetometer number ''num''. | + | |
- | + | ||
- | magnetometer_turn_on(num) -> err | + | |
- | + | ||
- | The function ''magnetometer_turn_on'' turns on (activates) a magnetometer number ''num''. | + | |
- | + | ||
- | ==== Interface Motor ==== | + | |
- | + | ||
- | These interface functions are designed to control [[wheel_subsys|flywheels]]. The argument ''num'' is the number of the flywheel (it can take values from ''0'' to ''3''). | + | |
- | + | ||
- | motor_get_state(num) -> ready | + | |
- | The function ''motor_get_state'' returns the readiness flag of flywheel number ''num'': ''1'' - ready; ''0'' - not ready. | ||
motor_request_reset(num) -> err | motor_request_reset(num) -> err | ||
- | The function ''motor_request_reset'' resets the controller of flywheel number ''num''. | + | The ''motor_request_reset'' function resets the reaction wheel controller for the wheel ''num''. |
motor_request_speed(num) -> (err, value) | motor_request_speed(num) -> (err, value) | ||
- | The function ''motor_request_speed'' returns a list of values: ''err'' - error code; ''value'' - the current speed of the flywheel number ''num''. | + | The ''motor_request_speed'' function returns a list where ''err'' is the error code and ''value'' is the current rotation speed of the wheel ''num''. |
motor_set_speed(num, value) -> (err, value) | motor_set_speed(num, value) -> (err, value) | ||
- | The function ''motor_set_speed'' sets the speed of flywheel number ''num'' to ''value''. The function returns a list of values: ''err'' - error code; ''value'' is the speed measured by the controller after installation. | + | The ''motor_set_speed'' function requests a new speed value for the wheel ''num''. This function returns a list of values where err is the error code and value is the speed read back by the controller after setting. |
<code python> | <code python> | ||
Line 247: | Line 182: | ||
</code> | </code> | ||
- | > **IMPORTANT**: The set value of speed (the second argument of the function) and the return value of the speed (the second element of the return value list) must be close in value and sign (speed direction). If the function returns an error code other than ''0'', then you cannot trust the return value of the speed! | + | <note important> |
+ | **//**IMPORTANT**: The set value of speed (the second argument of the function) and the return value of the speed (the second element of the return value list) must be close in value and sign (speed direction). If the function returns an error code other than ''0'', then you cannot trust the return value of the speed!//** | ||
+ | </note> | ||
motor_turn_off(num) -> err | motor_turn_off(num) -> err | ||
- | The function ''motor_turn_off'' turns off the flywheel number ''num''. | + | The ''motor_turn_off'' function turns off the reaction wheel ''num''. |
motor_turn_on(num) -> err | motor_turn_on(num) -> err | ||
- | The function ''motor_turn_on'' turns on (activates) the flywheel number ''num''. | + | |
+ | The ''motor_turn_on'' function turns on (activates) the reaction wheel ''num''. | ||
==== Interface Sunbattery ==== | ==== Interface Sunbattery ==== | ||
Line 272: | Line 210: | ||
The function ''sunbattery_request_reset'' resets the controller of the solar cell element number ''num''. | The function ''sunbattery_request_reset'' resets the controller of the solar cell element number ''num''. | ||
- | ==== Interface sun_sensor ==== | + | **Earth Observation Camera** |
+ | <code python>camera_get_state() -> ready</code> | ||
+ | The ''camera_get_state'' function returns the device readiness flag: 1 – the device is ready, 0 – not ready. | ||
+ | <code python>camera_take_photo(frame) -> err</code> | ||
+ | The ''camera_take_photo'' function captures an image with number referred to by the frame argument. Your images will generally be numbered 0 to 9. The function returns 0 upon successful completion or a non-zero value otherwise. | ||
+ | <code python>camera_turn_off() -> err</code> | ||
+ | The ''camera_turn_off function'' turns off the device. | ||
+ | <code python>camera_turn_on() -> err</code> | ||
+ | The ''camera_turn_on function'' turns on (activates) the device. | ||
- | This set of interface functions is designed to work with [[sun_subsys|solar sensors]]. Argument ''num'' is the sensor number (it can take values from ''0'' to ''7''). | + | **Interface Transmitter** |
- | sun_sensor_get_state(num) -> ready | + | These interface functions control HF transmitters. The ''transmitter_transmit_photo'' function transfers previously shot and saved images. The ''num'' argument references the HF transmitter (within the range from 0 to 3). |
- | The function ''sun_sensor_get_state'' returns the flag of readiness of the solar sensor number ''num'': ''1'' - ready; ''0'' -- not ready. | + | transmitter_get_state(num) -> ready |
- | sun_sensor_request_maxraw(num) -> (err, value) | + | The ''transmitter_get_state'' function returns the readiness flag for the HF transmitter ''num''. |
- | The function ''sun_sensor_request_maxraw'' returns a list: ''err'' - error code; ''value'' - the maximum value of solar sensor number ''num'' readings. | + | transmitter_request_reset(num) -> err |
- | sun_sensor_request_raw(num) -> (err, value, value) | + | The ''transmitter_request_reset'' resets the HF transmitter ''num''. |
- | The function ''sun_sensor_request_raw'' returns a list: ''err'' - error code; ''value'' - current readings of the solar sensor number ''num''. | + | transmitter_transmit_photo(num, frame) -> err |
- | sun_sensor_request_reset(num) -> err | + | The ''transmitter_transmit_photo'' function transfers an image referenced by frame using the HF transmitter ''num''. The function will return 0 if the image has been transferred successfully. |
- | The function ''sun_sensor_request_reset'' performs a reset of the solar sensor number ''num''. | + | transmitter_turn_off(num) -> err |
- | sun_sensor_set_calibrate(num, value) -> err | + | The ''transmitter_turn_off'' function turns off the HF transmitter ''num''. |
- | The function ''sun_sensor_set_calibrate'' calibrates the sensor (sets the mode to ''value'' for the sensor number ''num''). Currently, this function is not used. | + | transmitter_turn_on(num) -> err |
- | + | ||
- | sun_sensor_set_minvalue(num, value) -> err | + | |
- | + | ||
- | The function ''sun_sensor_set_minvalue'' is not used. | + | |
- | + | ||
- | sun_sensor_turn_off(num) -> err | + | |
- | + | ||
- | The function ''sun_sensor_turn_off'' turns off the solar sensor number ''num''. | + | |
- | + | ||
- | sun_sensor_turn_on(num) -> err | + | |
- | + | ||
- | The function ''sun_sensor_turn_on'' turns on (activates) the solar sensor number ''num''. | + | |
- | + | ||
- | sun_sensors_angle(value, value, value) -> value | + | |
- | + | ||
- | The function ''sun_sensors_angle'' is not a control function. This is a computational auxiliary function that returns a value in the form of a double precision number with a fixed point. | + | |
- | [TBD] | + | The ''transmitter_turn_on'' turns on the HF transmitter ''num''. |
- | ==== Interface Transceiver ==== | + | **Interface Transceiver** |
- | These interface functions control sixteen [[uhf_tx_subsys|telemetry transmitters]]; they are used to transmit and receive data arrays (telemetry). The ''num'' argument is the number of the telemetry transmitter (it can take values from ''0'' to ''15''). | + | These interface functions control sixteen telemetry transceivers; they are used for sending and receiving data arrays (telemetry). The num argument references the telemetry transceiver (within the range from 0 to 15). |
transceiver_get_state(num) -> ready | transceiver_get_state(num) -> ready | ||
- | The function ''transceiver_get_state'' returns the readiness flag value of the telemetry transmitters: ''1'' - ready; ''0'' -- not ready. | + | The ''transceiver_get_state'' function returns the telemetry transceiver readiness flag: 1 – the transceiver is ready; 0 – not ready. |
transceiver_request_buff(num) -> (err, data) | transceiver_request_buff(num) -> (err, data) | ||
- | The function ''transceiver_request_buff'' queries the contents of the receiver buffer and returns a list of values: ''err'' - error code; ''data'' - contents of the buffer (32 bytes). | + | The ''transceiver_request_buff'' requests the contents of the receiver buffer and returns a list of values where ''err'' is the error code and ''data'' contains buffered data (32 bytes). |
transceiver_request_reset(num) -> err | transceiver_request_reset(num) -> err | ||
- | The function ''transceiver_request_reset'' resets the telemetry transmitter number ''num''. | + | The ''transceiver_request_reset'' function resets the telemetry transceiver ''num''. |
transceiver_send(txnum, rxnum, data) -> err | transceiver_send(txnum, rxnum, data) -> err | ||
- | The function ''transceiver_send'' transfers ''data'' from the transmitter number ''txnum'' to the receiver number ''rxnum''. In the case of successful data translation, the function returns ''0''. | + | The ''transceiver_send'' function sends data in data using transmitter ''txnum'' to the receiver ''rxnum''. The function returns 0 if the data has been broadcast successfully. |
<code python> | <code python> | ||
err = transceiver_send(1, 0, b'hello, world!') | err = transceiver_send(1, 0, b'hello, world!') | ||
if err: | if err: | ||
- | print 'Transfer Error!' | + | print 'Transmission error!' |
</code> | </code> | ||
transceiver_turn_off(num) -> err | transceiver_turn_off(num) -> err | ||
- | The function ''transceiver_turn_off'' turns off the telemetry transmitter number ''num''. | + | The ''transceiver_turn_off'' function turns off the telemetry transceiver ''num''. |
transceiver_turn_on(num) -> err | transceiver_turn_on(num) -> err | ||
- | The function ''transceiver_turn_on'' turns on (activates) a telemetry transmitter number ''num''. | + | The ''transceiver_turn_on'' function turns on (activates) the telemetry transceiver ''num''. |
- | ==== Interface Transmitter ==== | + | **Solar Battery** |
- | These interface functions control [[hf_tx_subsys|the HF transmitters]]. The transmission of pre-captured and saved photos is carried out using the function ''transmitter_transmit_photo''. The argument ''num'' is the number of the HF transmitter (it can take values from ''0'' to ''3''). | + | The ''num'' argument is the solar battery cell number (ranging from 0 to 7). |
+ | <code python>sunbattery_request_maxraw(num) -> (err, value)</code> | ||
+ | The ''sunbattery_request_maxraw'' function returns a list where ''err'' is the error code and ''value'' is the maximum value of the parameter received from the solar cell ''num''. | ||
+ | <code python>sunbattery_request_raw(num) -> (err, value)</code> | ||
+ | The ''sunbattery_request_raw'' function returns a list where ''err'' is the error code and ''value'' is the current value of the parameter received from the solar cell ''num''. | ||
+ | <code python>sunbattery_request_reset(num) -> err</code> | ||
+ | The ''sunbattery_request_reset'' function resets the controller of the solar cell ''num''. | ||
- | transmitter_get_state(num) -> ready | + | **Getting Into Details** |
- | + | ||
- | The function ''transmitter_get_state'' returns the readiness flag of HF transmitter number ''num''. | + | |
- | + | ||
- | transmitter_request_reset(num) -> err | + | |
- | + | ||
- | The function ''transmitter_request_reset'' resets the HF transmitter number ''num''. | + | |
- | + | ||
- | transmitter_transmit_photo(num, frame) -> err | + | |
- | + | ||
- | The function ''transmitter_transmit_photo'' transmits a photo with the "frame" number using the HF transmitter with number ''num''. If the photo is successfully transmitted, the function returns ''0''. | + | |
- | + | ||
- | transmitter_turn_off(num) -> err | + | |
- | + | ||
- | The function ''transmitter_turn_off'' turns off the HF transmitter number ''num''. | + | |
- | + | ||
- | transmitter_turn_on(num) -> err | + | |
- | + | ||
- | The function ''transmitter_turn_on'' turns on HF transmitter number ''num''. | + | |
- | ===== Some details ===== | + | **The Runtime Environment** |
- | ==== Runtime Environment ==== | + | Projects in Python, similar to projects in C, can be managed in a development environment built around the notepad++ editor. A ZIP archive prepared in the development environment will contain an automatically generated Python script for deployment with your file embedded into the script. To illustrate, the script will have approximately the following skeleton structure: |
- | Projects in Python as well as projects in C, can be prepared using the interface of [[gui_interface|the programming environment]] based on the [[https://notepad-plus-plus.org|''notepad++'']] editor. A zip-archive, prepared in the programming environment, contains an automatically generated Python script for execution. This script includes the contents of your file. Schematically, and very simplistically, the script can be written as follows: | + | |
<code python> | <code python> | ||
Line 381: | Line 298: | ||
from time import sleep, time | from time import sleep, time | ||
#------------------------------------------------------------------->8 | #------------------------------------------------------------------->8 | ||
- | # Your Python code, which necessarily includes the implementation of the control () function. | + | # Your Python that must implement the control() function. |
#------------------------------------------------------------------->8 | #------------------------------------------------------------------->8 | ||
if __name__ == "__main__": | if __name__ == "__main__": | ||
Line 387: | Line 304: | ||
</code> | </code> | ||
- | Now it should become clear why we can use the ''sleep'' function from the ''time'' module in our programs. It is also obvious that your code can import additional Python modules, for example: | + | It is now evident why we can invoke the sleep function from the time module in our programs. It is also evident that your code can import additional Python modules, for example: |
<code python> | <code python> | ||
Line 396: | Line 313: | ||
</code> | </code> | ||
- | ==== Ready flag and error codes ==== | + | **The Readiness Flag and Return Codes** |
Interface functions of the form | Interface functions of the form | ||
- | <code python> | + | <code python>interface_get_state(...) -> ready</code> |
- | interface_get_state(...) -> ready | + | |
- | </code> | + | |
- | return an unsigned integer - the device readiness flag. If the return value is ''1'', it means that the device is ready and you can work with the device (interface). For example, you can subtract data from the sensor or turn on the actuator. If the function returned ''0'', it means that the device was not prepared for operation, and you did not activate the interface (did not call the corresponding ''interface_turn_on'' function). | + | return an unsigned integer – the device readiness flag. When the value returned is 1, this means the device is ready and the device (or the interface) can be worked with. For example, data can be read out of the sensor or an actuator can be turned on. If the function returns 0 that means the device has not been initialized for operation yet or that the interface has not yet been activated (by calling the respective interface_turn_on function). |
- | > **ATTENTION**: The readiness of the device only means that you can start using the device. The ready flag does not mean that the functions called later will return valid data or that the device will accept commands. Be sure to check the error codes returned by the interface functions! | + | <note important> |
+ | **//ATTENTION: Device readiness only means that you can begin working with the device. The readiness flag does not imply that any subsequently called functions will return valid data or that the device will respond to commands it receives. Always check return codes from interface functions!//** | ||
+ | </note> | ||
Interface functions of the form | Interface functions of the form | ||
- | <code python> | + | <code python>interface_do_something(...) -> err |
- | interface_do_something(...) -> err | + | interface_do_something(...) -> (err, ...)</code> |
- | interface_do_something(...) -> (err, ...) | + | |
- | </code> | + | |
- | return unsigned integer -- error code. The returned error code can be ''0'' -- //no errors//, ''1'' -- //interface error// or ''2'' -- //access error//. | + | return an unsigned integer – the error code. The following error codes can be returned: 0 – ''no errors'', 1 – ''interface error'' or 2 – ''access error''. |
+ | The ''interface error'' code is returned when an interface function is used in an invalid manner e.g. a nonexistent device number is specified or there is an error on the information bus blocking data from being read back. | ||
+ | |||
+ | The ''access error'' code is returned in response to an attempted request of data from a device that is not ready, e.g. when accessing a device that has not been powered on yet. | ||
+ | |||
+ | To know the type of error that occurred just print out the err variable: | ||
+ | |||
+ | <code python>if err: | ||
+ | print 'Error: %d' % err</code> | ||
- | The //"interface error"// code is returned when the interface function is misused, for example, when a non-existent device number is specified or when noise occurred on the data bus and data could not be read. | ||
- | The //"access error"// code is returned when you try to request data from a device that is not yet ready, for example, accessing a device that was not previously enabled. | ||
- | If you want to know the type of error that occurred, simply print the ''err'' variable: | ||
- | <code python> | ||
- | if err: | ||
- | print 'Error: %d' % err | ||
- | </code> | ||