Description of Python Function Libraries
Functions described below are used for interaction with Orbicraft construction set subsystems by programs written in Python version 2.7.
Quick Start
Here is what you need to create a bare-bones 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
# My first Python project def control(): print 'Hello world!'
Introduction
Our function descriptions will include:
Example
hyro_request_reset(num) -> err
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 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 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:
err = hyro_request_reset(0) if err: print 'An error occurred!'
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. This example is for the interface named hyro
:
hyro_request_reset(num) # reset (initialize) the interface sleep(1.0/2) # Make a short delay – half a second for example hyro_turn_on(num) # Turn on (activate) the interface ready = hyro_get_state(num) # Check whether the interface is ready if ready: # Do something sensible e.g. capture 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) # Never forget to turn off the interface!
Subsystem Functions
Functions working with subsystems are described below.
Orbiter Power System (OPS)
These functions check the state of OPS virtual battery. They take no arguments. All functions return a single-precision floating-point value.
battery_get_charge() -> value
The battery_get_charge
returns the remaining capacity of the battery in ampere-hours.
battery_get_charging_current() -> value
The battery_get_charging_current
function returns the instantaneous battery charge current value in milliamperes.
battery_get_discharging_current() -> value
The battery_get_discharging_current
function returns the instantaneous battery discharge current value in milliamperes.
Magnetometer
The num
argument is the magnetometer ID (within the range of 0 to 3).
magnetometer_get_state(num) -> ready
The magnetometer_get_state
function returns a readiness flag for the magnetometer num
.
magnetometer_request_raw(num) -> (err, x, y, z)
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
.
magnetometer_request_reset(num) -> err
The magnetometer_request_reset
function resets the magnetometer num
.
magnetometer_turn_off(num) -> err
The magnetometer_turn_off
turns off the magnetometer num
.
magnetometer_turn_on(num) -> err
The magnetometer_turn_on function
turns on (activates) the magnetometer num
.
Angular Velocity Sensor (AVS)
These functions are for interfacing with the angular velocity sensor (AVS). The num
argument identifies the sensor (within the range of 0 to 3).
hyro_get_state(num) -> ready
The hyro_get_state
returns the device readiness flag: 1 – the sensor is ready; 0 – not ready.
hyro_request_raw(num) -> (err, x, y, z)
The hyro_request_raw
function returns a list consisting of error code err
and current AVS readings: x, y, z
.
hyro_request_reset(num) -> err
The hyro_request_reset
function resets the sensor num
.
hyro_turn_off(num) -> err
The hyro_turn_off
turns off the sensor num
.
hyro_turn_on(num) -> err
The hyro_turn_on
function turns on (activates) the sensor num
.
Solar Sensor
The num
argument identifies the sensor (within the range of 0 to 7).
sun_sensor_get_state(num) -> 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.
sun_sensor_request_maxraw(num) -> (err, value)
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
.
sun_sensor_request_raw(num) -> (err, value, value)
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
.
sun_sensor_request_reset(num) -> err
The sun_sensor_request_reset
function resets the sensor num
.
sun_sensor_set_calibrate(num, value) -> err
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.
sun_sensor_set_minvalue(num, value) -> err
The sun_sensor_set_minvalue
function is not used.
sun_sensor_turn_off(num) -> err
The sun_sensor_turn_off
function turns off the solar sensor num
.
sun_sensor_turn_on(num) -> err
The sun_sensor_turn_on
function turns on (activates) the solar sensor num
.
sun_sensors_angle(value, value, value) -> value
The sun_sensors_angle
function performs no control operations. It is a computational utility function that returns a double-precision floating-point value.
Reaction Wheel
The num
argument is the reaction wheel ID (within the range of 0 to 3).
motor_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.
motor_request_reset(num) -> err
The motor_request_reset
function resets the reaction wheel controller for the wheel num
.
motor_request_speed(num) -> (err, value)
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)
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.
num = 0 write_speed = -100 (err, read_speed) = motor_set_speed(num, write_speed) if not err: print (write_speed, read_speed)
0
, then you cannot trust the return value of the speed!
motor_turn_off(num) -> err
The motor_turn_off
function turns off the reaction wheel num
.
motor_turn_on(num) -> err
The motor_turn_on
function turns on (activates) the reaction wheel num
.
These interface functions allow you to read the parameters of solar cell elements. The argument num
is the number of the solar cell element (it can take values from 0
to 7
).
sunbattery_request_maxraw(num) -> (err, value)
The function sunbattery_request_maxraw
returns a list of values: err
- error code and value
- the maximum value of the parameter received from the solar element 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 value of the parameter received from the solar element number num
.
sunbattery_request_reset(num) -> err
The function sunbattery_request_reset
resets the controller of the solar cell element number num
.
Earth Observation Camera
camera_get_state() -> ready
The camera_get_state
function returns the device readiness flag: 1 – the device is ready, 0 – not ready.
camera_take_photo(frame) -> err
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.
camera_turn_off() -> err
The camera_turn_off function
turns off the device.
camera_turn_on() -> err
The camera_turn_on function
turns on (activates) the device.
Interface Transmitter
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).
transmitter_get_state(num) -> ready
The transmitter_get_state
function returns the readiness flag for the HF transmitter num
.
transmitter_request_reset(num) -> err
The transmitter_request_reset
resets the HF transmitter num
.
transmitter_transmit_photo(num, frame) -> 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.
transmitter_turn_off(num) -> err
The transmitter_turn_off
function turns off the HF transmitter num
.
transmitter_turn_on(num) -> err
The transmitter_turn_on
turns on the HF transmitter num
.
Interface Transceiver
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
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)
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
The transceiver_request_reset
function resets the telemetry transceiver num
.
transceiver_send(txnum, rxnum, data) -> err
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.
err = transceiver_send(1, 0, b'hello, world!') if err: print 'Transmission error!'
transceiver_turn_off(num) -> err
The transceiver_turn_off
function turns off the telemetry transceiver num
.
transceiver_turn_on(num) -> err
The transceiver_turn_on
function turns on (activates) the telemetry transceiver num
.
Solar Battery
The num
argument is the solar battery cell number (ranging from 0 to 7).
sunbattery_request_maxraw(num) -> (err, value)
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
.
sunbattery_request_raw(num) -> (err, value)
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
.
sunbattery_request_reset(num) -> err
The sunbattery_request_reset
function resets the controller of the solar cell num
.
Getting Into Details
The 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:
from schsat import * from time import sleep, time #------------------------------------------------------------------->8 # Your Python that must implement the control() function. #------------------------------------------------------------------->8 if __name__ == "__main__": control()
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:
import math def control(): print (math.e) print (math.pi)
The Readiness Flag and Return Codes
Interface functions of the form
interface_get_state(...) -> ready
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).
Interface functions of the form
interface_do_something(...) -> err interface_do_something(...) -> (err, ...)
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:
if err: print 'Error: %d' % err