User Tools

Site Tools


en:libschsat-py

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

en:libschsat-py [2019/12/30 17:18]
golikov
en:libschsat-py [2020/03/25 16:28]
Line 1: Line 1:
-**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 
- 
-<file python hello.py>​ 
-# My first Python project ​ 
-def control(): 
- print 'Hello world!'​ 
-</​file>​ 
- 
-**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: 
- 
-<code python> 
-err = hyro_request_reset(0) 
-if err: 
- print 'An error occurred!'​ 
-</​code>​ 
- 
-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'':​ 
- 
-<code python> 
-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! 
-</​code>​ 
- 
-**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. 
- 
-<code python>​battery_get_charge() -> value</​code>​ 
-The ''​battery_get_charge''​ returns the remaining capacity of the battery in ampere-hours. 
- 
-<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. 
- 
-**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). 
-<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''​. 
- 
-**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. 
- 
-<code python> 
-num = 0 
-write_speed = -100 
-(err, read_speed) = motor_set_speed(num,​ write_speed) 
-if not err: 
- print (write_speed,​ read_speed) 
-</​code>​ 
- 
-<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 
- 
-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 [[sun_battery|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** 
-<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. 
- 
-**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. 
- 
-<code python> 
-err = transceiver_send(1,​ 0, b'​hello,​ world!'​) 
-if err: 
- print '​Transmission error!'​ 
-</​code>​ 
- 
- 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). 
-<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''​. 
- 
-**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: 
- 
-<code python> 
-from schsat import * 
-from time import sleep, time 
-#​------------------------------------------------------------------->​8 
-# Your Python that must implement the control() function. 
-#​------------------------------------------------------------------->​8 
-if __name__ == "​__main__":​ 
- control() 
-</​code>​ 
- 
-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> 
-import math 
-def control(): 
- print (math.e) 
- print (math.pi) 
-</​code>​ 
- 
-**The Readiness Flag and Return Codes** 
- 
-Interface functions of the form 
- 
-<code python>​interface_get_state(...) -> ready</​code>​ 
- 
-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). 
- 
-<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 
- 
-<code python>​interface_do_something(...) -> err 
-interface_do_something(...) -> (err, ...)</​code>​ 
- 
-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>​ 
- 
- 
- 
  
en/libschsat-py.txt · Last modified: 2020/03/25 16:28 (external edit)