Description of Python function libraries
The functions described below are used to interact with subsystems when writing programs for the OrbiCraft satellite constructor in Python version 2.7.
Quick start
In order to create a simple Python project:
1) 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 .
2) Implement a function named control in Python.
The control() function is the entry point to your Python code, look at it as the main() function.
An example of a simple Python project: ``cpp hello.py
My first Python project
def control(): print 'Hello world!' ``
Introduction
When describing the functions, we will specify:
- Function name (the function name is unique);
- list of arguments for this function;
- a list of values returned by the function.
Example: ``cpp hyro_request_reset(num) -> err
The example above describes an interface named `'hyro_request_reset`" – this is the name of a Python function; the function takes one argument **num** (sensor number) and returns a single value – **err** (error code).
Most functions expect that the device number (the number of the sensor or actuator of this type) is passed as the first argument. Usually the device number is a number from **0** before **3** . Also, most functions return the value of the execution status of the called function (return an error code). In the example above, this fact is marked as a pair of characters → **err**.
When using functions, it is important to analyze the returned error code (value **err**). If the called function terminated without an error, it returns zero **(0)**, otherwise it returns a value other than zero. An example of processing a value returned by a function
```cpp
err = hyro_request_reset(0)
if err:
print 'Error!'
``
Functions with the names `interface_request_reset`, `interface_get_state`, `interface_turn_on()` and `interface_turn_off` are often found, where **interface** is the interface name.
These functions are typically used as follows. An example for the hyro interface
```cpp
hyro_request_reset(num) # reset(initialize)
the sleep interface(1.0/2) # wait a bit, for example 1/2 sec.
hyro_turn_on(num) # enable(activate) the interface
ready = hyro_get_state(num) # check the readiness of the interface
if ready:
# do something useful, like take readings
(err, x, y, z) = hyro_request_raw(num)
if not err:
print 'x=%d y=%d z=%d' % (x, y, z)
hyro_turn_off(num) # be sure to turn off the interface!
``
## Subsystem functions
The functions for working with subsystems are described below.
### Power Supply System (PSS)
These functions allow you to determine the status of the PSS virtual battery. No arguments are passed to these functions. Each of the functions returns a parameter as a single precision floating point number.
```cpp
battery_get_charge() -> value
The 'battery_get_charge` function returns the current battery charge value expressed in ampere hours.
battery_get_charging_current() -> value
The function battery_get_charging_current returns the current value of the charge current in milliamps.
battery_get_discharging_current() -> value
The function battery_get_discharging_current returns the current value of the discharge current in milliamps.
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 magnetometer readiness flag with the 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 – current readings of the magnetometer with the number num.
magnetometer_request_reset(num) -> err
The function magnetometer_request_reset resets the magnetometer with the number num.
magnetometer_turn_off(num) -> err
The `magnetometer_turn_off function turns off the magnetometer with the number num.
magnetometer_turn_on(num) -> err
The function magnetometer_turn_on turns on (activates) the magnetometer with the number num.
Angular Velocity Sensor (AVS)
These interface functions are used to work with the angular velocity sensor (AVS). The num argument is the sensor number (it can take values from 0 to 3).
hyro_get_state(num) -> ready
The function hyro_get_state returns the device readiness flag: 1 – the sensor is ready; 0 – No, it's not.
hyro_request_raw(num) -> (err, x, y, z)
The function `hyro_request_raw" returns a list: error code err and current AVS readings: x, y, z.
hyro_request_reset(num) -> err
The function hyro_request_reset resets the sensor with the number num.
hyro_turn_off(num) -> err
The hyro_turn_off function turns off the sensor with the number num.
hyro_turn_on(num) -> err
The hyro_turn_on function turns on (activates) the sensor with the number num.
Solar sensor
The num argument is the sensor number (it can take values from 0 to 7).
sun_sensor_get_state(num) -> ready
The function sun_sensor_get_state returns the readiness flag of the solar sensor with the number num: 1 – the sensor is ready; 0 – No, it's not.
sun_sensor_request_maxraw(num) -> (err, value)
The function sun_sensor_request_maxraw returns a list: err – error code; value – maximum readings of the solar sensor with the number num.
sun_sensor_request_raw(num) -> (err, value, value)
The function `sun_sensor_request_raw" returns a list: err – error code; value – current readings of the solar sensor with the number num.
sun_sensor_request_reset(num) -> err
The function sun_sensor_request_reset resets the solar sensor with the number num.
sun_sensor_set_calibrate(num, value) -> err
The function sun_sensor_set_calibrate calibrates the sensor (sets the mode to value for the sensor with the number num). This feature is not currently in use.
sun_sensor_set_minvalue(num, value) -> err
The function sun_sensor_set_minvalue is not used.
sun_sensor_turn_off(num) -> err
The `sun_sensor_turn_off function turns off the solar sensor with the number num.
sun_sensor_turn_on(num) -> err
The function `sun_sensor_turn_on" turns on (activates) the solar sensor with the number num.
sun_sensors_angle(value, value, value) -> value
The sun_sensors_angle function is not a control function. It is a computational auxiliary function that returns a value as a double-precision fixed-point number.
Flywheel engine
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 flywheel readiness flag with the number num: 1 – ready; 0 – No, it's not.
motor_request_reset(num) -> err
The motor_request_reset function resets the flywheel control controller with the number num.
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 with the number num.
motor_set_speed(num, value) -> (err, value)
The function motor_set_speed sets the speed of the flywheel with the number num to the value value. The function returns a list of values: err – error code; value – the speed value measured by the controller after installation.
num = 0
write_speed = -100
(err, read_speed) = motor_set_speed(num, write_speed)
if not err:
print (write_speed, read_speed)
important! The set speed value (the second argument of the function) and the returned speed values (the second element of the list of returned values) must be close values in magnitude and sign (direction of speed). If the function returns an error code other than 0, then you cannot trust the returned speed value!
motor_turn_off(num) -> err
The `motor_turn_off function turns off the flywheel with the number num.
motor_turn_on(num) -> err
The 'motor_turn_on` function enables (activates) the flywheel with the number num.
ERS Camera
camera_get_state() -> ready
The function camera_get_state returns the device readiness flag: 1 – the device is ready, 0 – No, it's not.
camera_take_photo(frame) -> err
The function `'camera_take_photo`` takes a picture with the number specified using the frame argument. You usually number photos with numbers from 0 before 9 . The function returns 0 in case of successful completion of the action, otherwise – a value other than zero.
camera_turn_off() -> err
The `camera_turn_off function turns off the device.
camera_turn_on() -> err
The function camera_turn_on enables (activates) device.
HF radio channel
The present interface functions control HF transmitters. Using the `transmitter_transmit_photo function, pre-captured and saved photo frames are transmitted. The argument num is the HF transmitter number (can take values from 0 before 3 ).
transmitter_get_state(num) -> ready
The function transmitter_get_state returns the HF transmitter readiness flag with the number num.
transmitter_request_reset(num) -> err
The function transmitter_request_reset resets the HF transmitter with the number num.
transmitter_transmit_photo(num, frame) -> err
The `transmitter_transmit_photo function transmits a photo with the number frame using an HF transmitter with the number num. In case of successful frame transfer, the function returns 0 .
transmitter_turn_off(num) -> err
The `transmitter_turn_off function turns off the HF transmitter with the number num.
transmitter_turn_on(num) -> err
The function transmitter_turn_on turns on the HF transmitter with the number num.
VHF radio channel
These interface functions control sixteen telemetry transmitters; they are used to transmit and receive arrays of data (telemetry). The argument num is the number of the telemetry transmitter (it can take values from 0 to 15).
transceiver_get_state(num) -> ready
The function transceiver_get_state returns the value of the readiness flag by telemetry transmitters: 1 – the transmitter is ready; 0 – No, it's not.
transceiver_request_buff(num) -> (err, data)
The function transceiver_request_buff requests the contents of the receiver buffer and returns a list of values: err – error code; data – buffer contents (32 bytes).
transceiver_request_reset(num) -> err
The `transceiver_request_reset function resets the telemetry transmitter with the number num.
transceiver_send(txnum, rxnum, data) -> err
The `transceiver_send function transmits data data in the direction from the transmitter with the number txnum to the receiver with the number rxnum. In case of successful data translation, the function returns 0 .
err = transceiver_send(1, 0, b'hello, world!')
if err:
print 'Transmission error!'
``
```cpp
transceiver_turn_off(num) -> err
The `transceiver_turn_off function turns off the telemetry transmitter with the number num.
transceiver_turn_on(num) -> err
The function transceiver_turn_on enables (activates) a telemetry transmitter with the number num.
Solar battery
The argument num is the number of the solar cell (can take values from 0 before 7 ).
sunbattery_request_maxraw(num) -> (err, value)
The function sunbattery_request_maxraw returns a list of values: err – error code and value – maximum parameter value received from the solar element with the number num.
sunbattery_request_raw(num) -> (err, value)
The function sunbattery_request_raw returns a list of values: err – error code and value – the current parameter value received from the solar element with the number num.
sunbattery_request_reset(num) -> err
The function sunbattery_request_reset resets the controller of the solar cell with the number num.
Some details
Runtime environment
Python projects, as well as projects executed in C, can be prepared using the interface of the programming environment based on the [notepad++] editor (/docs/orbicraft/instruction_for_working_with_orbicraft/required_software). The 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 is something like the following
from schsat import *
from time import sleep, time
#------------------------------------------------------------------->8
# Your Python code, which necessarily includes the implementation of the control function().
#------------------------------------------------------------------->8
if __name__ == "__main__":
control()
``
Now it becomes 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
```cpp
import math
def control():
print (math.e)
print (math.pi)
Readiness flag and error codes
Interface functions of the form
interface_get_state(...) -> ready
``
returns an unsigned integer – the device readiness flag. If the return value is **1** This 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** this means that the device was not prepared for operation, you did not activate the interface (you did not call the corresponding function ``interface_turn_on`").
:::warning
ATTENTION: The readiness of the device only means that you can start working with the device. The ready flag does not mean that the functions called later will return reliable data or the device will accept the issued command. Be sure to check the error codes returned by the interface functions!
:::
Interface functions of the form
```cpp
interface_do_something(...) -> err
interface_do_something(...) -> (err, ...)
``
returns an unsigned integer – the error code. The returned error code can be equal to **0** – There are no errors, **1** – interface error or **2** – access error.
The code "interface error" is returned when the interface function is incorrectly used, for example, a non-existent device number is specified, or when an interference occurred on the information bus and the data could not be read.
The code "access error" is returned in cases when you tried to request data from a device that is not ready yet, for example, you accessed a device that was not previously turned on.
If you want to find out the type of error that occurred, just print the variable **err**:
``cpp
if err:
print 'Error: %d' % err