User Tools

Translations of this page:

Site Tools


en:libschsat-py

This is an old revision of the document!


Python interface

[WORK IN PROGRESS]

Starting with version 1.02, the standard library includes support for the 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. 1)

Fast start

In order to create a simple Python project

  1. Put your Python code in a separate file with the extension .py 2)
  2. Implement a function named control in Python 3)

Here is an example of a simple Python project:

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

Interface Functions

In describing the interface functions, we will indicate:

  • function name (function name is unique)
  • list of arguments for this function
  • list of values returned by the function

Example

hyro_request_reset(num) -> err

In the example above, the interface named hyro_request_reset is shown. hyro_request_resetis the name of the Python function. The function takes one 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.

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:

err = hyro_request_reset(0)
if err:
	print 'Error!'

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.

These functions are generally used as follows (Example for the hyro interface):

hyro_request_reset(num)       # reset (initialize) the interface
sleep(1.0/2)                  # wait a little, for example, 1/2 second
hyro_turn_on(num)             # enable (activate) the interface
ready = hyro_get_state(num)   # Verify the interface is ready
if ready:
	# do something useful, for example, 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!

Interface Accelerometer

accelerometer_get_state(num) -> ready

[TBD]

accelerometer_request_raw(num) -> (err, x, y, z)

[TBD]

accelerometer_request_reset(num) -> err

[TBD]

accelerometer_turn_off(num) -> err

[TBD]

accelerometer_turn_on(num) -> err

[TBD]

Interface Battery

These interface functions allow you to determine the state of the virtual battery (PSS). These functions do not take any arguments. Each of the functions returns a parameter as a single-precision floating-point number.

battery_get_charge() -> value

The function battery_get_charge 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 milliamperes.

battery_get_discharging_current() -> value

The function battery_get_discharging_current returns the current value of the discharge current in milliamperes.

Interface Camera

This set of interface functions is designed to work with a camera.

camera_get_state() -> ready

The function camera_get_state returns the device ready flag: 1 - ready, 0 - not ready.

camera_take_photo(frame) -> err

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.

camera_turn_off() -> err

The function camera_turn_off turns off the device.

camera_turn_on() -> err

The function camera_turn_on turns on (activates) the device.

Interface Coil

coil_get_state(num) -> ready

[TBD]

coil_request_reset(num) -> err

[TBD]

coil_set_value(num, value) -> (err, value)

[TBD]

coil_turn_off(uint16_t num) -> err

[TBD]

coil_turn_on(num) -> err

[TBD]

Interface Light_sensor

light_sensor_get_state(num) -> 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 (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 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 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

The function motor_request_reset resets the controller of flywheel 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 number num.

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.

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 function motor_turn_off turns off the flywheel number num.

motor_turn_on(num) -> err

The function motor_turn_on turns on (activates) the flywheel number 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.

Interface sun_sensor

This set of interface functions is designed to work with solar sensors. Argument num 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 flag of readiness of the solar sensor number num: 1 - ready; 0 – not ready.

sun_sensor_request_maxraw(num) -> (err, value)

The function sun_sensor_request_maxraw returns a list: err - error code; value - the maximum value of solar sensor number num readings.

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 number num.

sun_sensor_request_reset(num) -> err

The function sun_sensor_request_reset performs a reset of the solar sensor 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 number num). Currently, this function is not used.

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]

Interface Transceiver

These interface functions control sixteen 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).

transceiver_get_state(num) -> ready

The function transceiver_get_state returns the readiness flag value of the telemetry transmitters: 1 - ready; 0 – not ready.

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

transceiver_request_reset(num) -> err

The function transceiver_request_reset resets the telemetry transmitter number num.

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.

err = transceiver_send(1, 0, b'hello, world!')
if err:
	print 'Transfer Error!'
transceiver_turn_off(num) -> err

The function transceiver_turn_off turns off the telemetry transmitter number num.

transceiver_turn_on(num) -> err

The function transceiver_turn_on turns on (activates) a telemetry transmitter number num.

Interface Transmitter

These interface functions control 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).

transmitter_get_state(num) -> ready

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

Runtime Environment

Projects in Python as well as projects in C, can be prepared using the interface of the programming environment based on the ''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:

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 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:

import math
def control():
	print (math.e)
	print (math.pi)

Ready flag and error codes

Interface functions of the form

interface_get_state(...) -> ready

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

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!

Interface functions of the form

interface_do_something(...) -> err
interface_do_something(...) -> (err, ...)

return unsigned integer – error code. The returned error code can be 0no errors, 1interface error or 2access error.

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:

if err:
	print 'Error: %d' % err
1)
The standard library is implemented in the low-level programming language С.
2)
The following reserved file names are not allowed: main.py and schsat.py.
3)
The function control () is the entry point to your Python code, look at it as a function main().
en/libschsat-py.1516889882.txt.gz · Last modified: 2018/01/25 17:18 by ashley