|
1 | | -**CalliopEO** |
2 | | - |
3 | | -***[README](README.md)*** | [Program Description](ProgramDescription.md) | [Testcases](testcases/testcases.md) |
4 | | -# Readme |
5 | | - |
6 | | -## Description |
7 | | -CalliopEO is a Python script to facilitate ineraction between a Raspberry Pi microcomputer and a [Calliope Mini microcontroller board](https://calliope.cc/). If executed, the script detects, if a Calliope Mini is attached to a USB board of the Raspbery Pi and determins the serial port to communicate the Calliope Mini. |
8 | | - |
9 | | -Place any program(s) to be executed by the Calliope Mini as zipped file(s) in the directory where the script `CalliopEO.py` resides. If executed the script will search for all zip archives, unpack the Calliope Mini program (HEX file) from the archive and flash the Calliope Mini with this program. After flashing, the Calliope Mini will reboot automatically and execute the program. |
10 | | - |
11 | | -In the directory a sub-folder named `run_YYYYMMDD-HHMMSS` will be created. The HEX files flashed and executed on the Calliope Mini will be copied to this folder along with any data sent back by the program (files will end with `.data`). The initial zip archive in the main folder is renamed (additional suffix `.done`) to exclude this file from being processed again. |
12 | | - |
13 | | -The `CalliopEO.py` script can collect data sent by the program on the Calliope Mini via the USB serial port. Therefore, prepare the Calliope Mini program to wait for the string `@START@`. Then, the Calliope Mini program should respond by sending `@START@` back to the `CalliopEO.py` script and only after this sending the data. After sending the data the Calliope Mini program should send the |
14 | | -message `@END@`. |
15 | | - |
16 | | -## Execute |
17 | | -``` |
18 | | -$ python3 CalliopEO.py [--max-data-size=bytes] [--max-script-execution-time=seconds] |
19 | | -``` |
20 | | -`--max-data-size` is the maximum number of characters to be read from the Calliope Mini (except newline characters). With `--max-script-execution-time` you can specify a maximum time to accept input from the Calliope Mini program before terminating the connection. |
21 | | - |
22 | | -## Hardware Setup |
23 | | -The Calliope Mini should be connected via USB to the Raspberry Pi. |
24 | | -``` |
25 | | - +--------------+ |
26 | | - | | USB o---o---o |
27 | | - | Raspberry Pi |===============| Call. | |
28 | | - | | o---o---o |
29 | | - +--------------+ |
30 | | -``` |
31 | | - |
32 | | -## Testing |
33 | | -To select and run tests execute `./testing.sh`. To get an overview of availbable tests see [Testcases.md](testcases/testcases.md). |
34 | | -Sample testresults can be found in [./testresults](testresults) |
35 | | - |
36 | | -## HEX Boilerplate |
37 | | - |
38 | | -For a sample implementation of the Boilerplate code for the Calliope mini please have a look at the [JS File](https://github.com/calliope-edu/CalliopEO_AstroPi/blob/06a4867b96a7cef7bf293340d21f18b37555aabc/testcases/testfiles/30sec-iss-sensors.js), the [Compiled HEX ](https://github.com/calliope-edu/CalliopEO_AstroPi/blob/06a4867b96a7cef7bf293340d21f18b37555aabc/testcases/testfiles/30sec-iss-sensors.hex) or edit it on [makecode.calliope.cc](https://makecode.calliope.cc/_KJT7WkEcwaDi). The .data file on the Raspberry Pi should look like this [this](https://github.com/calliope-edu/CalliopEO_AstroPi/blob/06a4867b96a7cef7bf293340d21f18b37555aabc/testcases/testfiles/30sec-iss-sensors.hex.data) |
39 | | - |
40 | | -## Software Installation |
41 | | -### Operating system |
42 | | -The project is intended to be used with the ESA [Astro Pi IR](https://astro-pi.org/) onboard the International Space Station ISS. The Astro Pi SBCs are running a dedicated flavour of Raspberry Pi OS not available for the public. But this software can also be installed on the publicly available [Raspberry Pi OS](https://www.raspberrypi.org/software/) running on any Raspberry Pi. For CalliopEO, the "OS Lite" version without desktop is sufficient. Follow the standard installation procedure. |
43 | | - |
44 | | -### Installation using the setup.sh script |
45 | | -To set up the environment for the `CalliopEO.py` script a setup script `setup.sh` was established. It automatically performs all necesaary steps to provide a fully functional environment. |
46 | | - |
47 | | -Before executing the setup script, connect the Calliope Mini to the Astro Pi/Raspberry Pi. Execute the setup script with the following command: |
48 | | -``` |
49 | | -$ sudo setup.sh [username] |
50 | | -``` |
51 | | -`username` is the name of the user to be created (enter without any brackets!). If this optional parameter is not given, the default `calliope` is used. |
52 | | - |
53 | | -The setup script performs the following actions: |
54 | | -* Create a dedicated user (default: `calliope`) |
55 | | -* Add user to group `dialout` to be able to perform communication with the Calliope Mini over the serial port |
56 | | -* Set password for the new user |
57 | | -* Determine UUIDs for Calliope Mini's block devices and creating mount points in `/etc/fstab`. Later, this is used to mount the block devices for flashing the Calliope Mini. The mount points are defined in `/etc/fstab` in order to allow unprivileged users like `calliope` to mount/unmount the block devices. |
58 | | -* Copying necessary files to the user's home directory into a subfolder `~/calliopEO`, in particular `CalliopEO.py` |
59 | | -* Installing necessary Python modules from local wheel files. This is necessary due to security requirements set by ESA. |
60 | | - |
61 | | -## De-Installation |
62 | | -The system can be cleaned up from the files necessary and the system settings done exclusively for CalliopEO using the procedure described as below. For this procedure it is assumed, that the username for the CalliopEO user is `calliope`. Replace `calliope` by the appropriate username if an alternative username was selected during the setup process (see above). |
63 | | - |
64 | | -1. Login to the Raspberry Pi using a user different from `calliope`. |
65 | | -2. Remove the user `calliope` with the command |
66 | | -``` |
67 | | -$ sudo userdel -r calliope |
68 | | -``` |
69 | | -3. Verify that the above command successfully removed the home directory `/home/calliope` with the command `ls /home/`. If the home directory still exists, remove it using the command `$ sudo rm -rf /home/calliope`. |
70 | | -4. Create a backup of the file `/etc/fstab` using the command |
71 | | -``` |
72 | | -$ sudo cp /etc/fstab /etc/fstab.backup |
73 | | -``` |
74 | | -5. Open the file `/etc/fstab` in a text editor. Remove (or uncomment) all mount point definitions in `/etc/fstab` for CalliopEO. The section with the moint point definitions should look like the following: |
75 | | -``` |
76 | | -# Mount points for Calliope Mini |
77 | | -/dev/disk/by-uuid/0123-4567 /home/calliope/mnt/mini vfat noauto,users 0 0 |
78 | | -/dev/disk/by-uuid/089A-BCDE /home/calliope/mnt/flash vfat noauto,users 0 0 |
79 | | -``` |
80 | | -6. Restart the operating system. The de-installation is complete. |
| 1 | +**CalliopEO** |
| 2 | + |
| 3 | +***[README](README.md)*** | [Program Description](ProgramDescription.md) | [Testcases](testcases/testcases.md) |
| 4 | +# Readme |
| 5 | + |
| 6 | +## Description |
| 7 | +CalliopEO is a Python script to facilitate ineraction between a Raspberry Pi microcomputer and a [Calliope Mini microcontroller board](https://calliope.cc/). If executed, the script detects, if a Calliope Mini is attached to a USB board of the Raspbery Pi and determins the serial port to communicate the Calliope Mini. |
| 8 | + |
| 9 | +Place any program(s) to be executed by the Calliope Mini as zipped file(s) in the directory where the script `CalliopEO.py` resides. If executed the script will search for all zip archives, unpack the Calliope Mini program (HEX file) from the archive and flash the Calliope Mini with this program. After flashing, the Calliope Mini will reboot automatically and execute the program. |
| 10 | + |
| 11 | +In the directory a sub-folder named `run_YYYYMMDD-HHMMSS` will be created. The HEX files flashed and executed on the Calliope Mini will be copied to this folder along with any data sent back by the program (files will end with `.data`). The initial zip archive in the main folder is renamed (additional suffix `.done`) to exclude this file from being processed again. |
| 12 | + |
| 13 | +The `CalliopEO.py` script can collect data sent by the program on the Calliope Mini via the USB serial port. Therefore, prepare the Calliope Mini program to wait for the string `@START@`. Then, the Calliope Mini program should respond by sending `@START@` back to the `CalliopEO.py` script and only after this sending the data. After sending the data the Calliope Mini program should send the |
| 14 | +message `@END@`. |
| 15 | + |
| 16 | +Each line in the `.data` files will have a leading time stamp of the format `YYYY/MM/DD-HH/MM/SS.ssssss`. |
| 17 | + |
| 18 | +## Execute |
| 19 | +``` |
| 20 | +$ python3 CalliopEO.py [--max-data-size=bytes] [--max-script-execution-time=seconds] [--fake-timestamp] |
| 21 | +``` |
| 22 | +* `--max-data-size` is the maximum number of characters to be read from the Calliope Mini. |
| 23 | +* With `--max-script-execution-time` you can specify a maximum time to accept input from the Calliope Mini program before terminating the connection. |
| 24 | +* `--fake-timestamp` adds to the beginning of each line a constant time stamp `2000/01/01-00:00:00.000000` instead of the current time stamp. This feature is primarily meant for testing purposes. |
| 25 | + |
| 26 | +## Hardware Setup |
| 27 | +The Calliope Mini should be connected via USB to the Raspberry Pi. |
| 28 | +``` |
| 29 | + +--------------+ |
| 30 | + | | USB o---o---o |
| 31 | + | Raspberry Pi |===============| Call. | |
| 32 | + | | o---o---o |
| 33 | + +--------------+ |
| 34 | +``` |
| 35 | + |
| 36 | +## Testing |
| 37 | +To select and run tests execute `./testing.sh`. To get an overview of availbable tests see [Testcases.md](testcases/testcases.md). |
| 38 | +Sample testresults can be found in [./testresults](testresults). |
| 39 | + |
| 40 | +## HEX Boilerplate |
| 41 | + |
| 42 | +For a sample implementation of the Boilerplate code for the Calliope mini please have a look at the [JS File](https://github.com/calliope-edu/CalliopEO_AstroPi/blob/06a4867b96a7cef7bf293340d21f18b37555aabc/testcases/testfiles/30sec-iss-sensors.js), the [Compiled HEX ](https://github.com/calliope-edu/CalliopEO_AstroPi/blob/06a4867b96a7cef7bf293340d21f18b37555aabc/testcases/testfiles/30sec-iss-sensors.hex) or edit it on [makecode.calliope.cc](https://makecode.calliope.cc/_KJT7WkEcwaDi). The .data file on the Raspberry Pi should look like this [this](https://github.com/calliope-edu/CalliopEO_AstroPi/blob/06a4867b96a7cef7bf293340d21f18b37555aabc/testcases/testfiles/30sec-iss-sensors.hex.data) |
| 43 | + |
| 44 | +## Software Installation |
| 45 | +### Operating system |
| 46 | +The project is intended to be used with the ESA [Astro Pi IR](https://astro-pi.org/) onboard the International Space Station ISS. The Astro Pi SBCs are running a dedicated flavour of Raspberry Pi OS not available for the public. But this software can also be installed on the publicly available [Raspberry Pi OS](https://www.raspberrypi.org/software/) running on any Raspberry Pi. For CalliopEO, the "OS Lite" version without desktop is sufficient. Follow the standard installation procedure. |
| 47 | + |
| 48 | +### Installation using the setup.sh script |
| 49 | +To set up the environment for the `CalliopEO.py` script a setup script `setup.sh` was established. It automatically performs all necesaary steps to provide a fully functional environment. |
| 50 | + |
| 51 | +Before executing the setup script, connect the Calliope Mini to the Astro Pi/Raspberry Pi. Execute the setup script with the following command: |
| 52 | +``` |
| 53 | +$ sudo setup.sh [username] |
| 54 | +``` |
| 55 | +`username` is the name of the user to be created (enter without any brackets!). If this optional parameter is not given, the default `calliope` is used. |
| 56 | + |
| 57 | +The setup script performs the following actions: |
| 58 | +* Create a dedicated user (default: `calliope`) |
| 59 | +* Add user to group `dialout` to be able to perform communication with the Calliope Mini over the serial port |
| 60 | +* Set password for the new user |
| 61 | +* Determine UUIDs for Calliope Mini's block devices and creating mount points in `/etc/fstab`. Later, this is used to mount the block devices for flashing the Calliope Mini. The mount points are defined in `/etc/fstab` in order to allow unprivileged users like `calliope` to mount/unmount the block devices. |
| 62 | +* Copying necessary files to the user's home directory into a subfolder `~/calliopEO`, in particular `CalliopEO.py` |
| 63 | +* Installing necessary Python modules from local wheel files. This is necessary due to security requirements set by ESA. |
| 64 | + |
| 65 | +## De-Installation |
| 66 | +The system can be cleaned up from the files necessary and the system settings done exclusively for CalliopEO using the procedure described as below. For this procedure it is assumed, that the username for the CalliopEO user is `calliope`. Replace `calliope` by the appropriate username if an alternative username was selected during the setup process (see above). |
| 67 | + |
| 68 | +1. Login to the Raspberry Pi using a user different from `calliope`. |
| 69 | +2. Remove the user `calliope` with the command |
| 70 | +``` |
| 71 | +$ sudo userdel -r calliope |
| 72 | +``` |
| 73 | +3. Verify that the above command successfully removed the home directory `/home/calliope` with the command `ls /home/`. If the home directory still exists, remove it using the command `$ sudo rm -rf /home/calliope`. |
| 74 | +4. Create a backup of the file `/etc/fstab` using the command |
| 75 | +``` |
| 76 | +$ sudo cp /etc/fstab /etc/fstab.backup |
| 77 | +``` |
| 78 | +5. Open the file `/etc/fstab` in a text editor. Remove (or uncomment) all mount point definitions in `/etc/fstab` for CalliopEO. The section with the moint point definitions should look like the following: |
| 79 | +``` |
| 80 | +# Mount points for Calliope Mini |
| 81 | +/dev/disk/by-uuid/0123-4567 /home/calliope/mnt/mini vfat noauto,users 0 0 |
| 82 | +/dev/disk/by-uuid/089A-BCDE /home/calliope/mnt/flash vfat noauto,users 0 0 |
| 83 | +``` |
| 84 | +6. Restart the operating system. The de-installation is complete. |
0 commit comments