User Tools

Translations of this page:

Site Tools


Sidebar

en:libschsat-py

Python Function Libraries

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

hello.py
# My first Python project 
def control():
	print 'Hello world!'

Introduction

Our function descriptions will include:

  • Function name (this name is unique)
  • A list of arguments accepted by the function
  • A list of values returned by the function.

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)
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!
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.

Interface Sunbattery

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).

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!

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
en/libschsat-py.txt · Last modified: 2020/03/25 16:28 (external edit)