First off, thank you for considering contributing to Scitizen 🔬.
It is people like you that make Scitizen such a great project 🚀.
In order to get familiar with the architecture behind Scitizen, please read our ARCHITECTURE guide.
The best way to extensively test the behavior of Scitizen is to test it directly on a physical device (like a Raspberry Pi).
In order to develop on a local device, follow these steps 👇
Fork this repository to your own GitHub account and then clone it to your local device.
You can find the installation instructions here.
Run the command
balena devices supportedExample of output
SLUG ALIASES ARCH NAME
asus-tinker-board armv7hf Asus Tinker Board
asus-tinker-board-s armv7hf Asus Tinker Board S
asus-tinker-edge-t aarch64 ASUS Tinker Edge T
bananapi-m1-plus armv7hf BananaPi-M1+
etcher-pro aarch64 Etcher Pro
fincm3 armv7hf Balena Fin (CM3)
generic amd64 Generic
generic-aarch64 aarch64 Generic AARCH64
genericx86-64-ext amd64 Generic x86_64
intel-edison edison i386 Intel Edison
intel-nuc nuc amd64 Intel NUC
jetson-nano aarch64 Nvidia Jetson Nano SD-CARD
jetson-nano-2gb-devkit aarch64 Nvidia Jetson Nano 2GB Devkit SD
jetson-nano-emmc aarch64 Nvidia Jetson Nano eMMC
jetson-tx1 aarch64 Nvidia Jetson TX1
jetson-tx2 aarch64 Nvidia Jetson TX2
jetson-tx2-nx-devkit aarch64 Nvidia Jetson TX2 NX (with Xavier NX Devkit)
jetson-xavier aarch64 Nvidia Jetson Xavier
jetson-xavier-nx-devkit aarch64 Nvidia Jetson Xavier NX Devkit SD-CARD
jetson-xavier-nx-devkit-emmc aarch64 Nvidia Jetson Xavier NX Devkit eMMC
jetson-xavier-nx-devkit-seeed-2mic-hat aarch64 Nvidia Jetson Xavier NX Devkit SD Seeed ReSpeaker-2Mic
jn30b-nano aarch64 Auvidea JN30B Nano
odroid-c1 armv7hf ODROID-C1+
odroid-xu4 odroid-ux3, odroid-u3+ armv7hf ODROID-XU4
orange-pi-one armv7hf Orange Pi One
orange-pi-zero armv7hf Orange Pi Zero
orangepi-plus2 armv7hf Orange Pi Plus2
raspberry-pi raspberrypi rpi Raspberry Pi (v1 / Zero / Zero W)
raspberry-pi2 raspberrypi2 armv7hf Raspberry Pi 2
raspberrypi3 armv7hf Raspberry Pi 3
raspberrypi3-64 aarch64 Raspberry Pi 3 (using 64bit OS)
raspberrypi4-64 aarch64 Raspberry Pi 4 (using 64bit OS)
raspberrypi400-64 aarch64 Raspberry Pi 400
raspberrypicm4-ioboard aarch64 Raspberry Pi CM4 IO Board
surface-go amd64 Microsoft Surface Go
surface-pro-6 amd64 Microsoft Surface 6Then, find the SLUG matching your device (in our example, we'll take raspberrypi4-64).
Run the command
balena os versions raspberrypi4-64Example of output
v2.80.5+rev1.prod (recommended)
v2.80.5+rev1.dev
v2.80.3+rev1.prod
v2.80.3+rev1.dev
v2.75.0+rev1.prod
v2.75.0+rev1.dev
v2.73.1+rev1.prod
v2.73.1+rev1.dev
v2.71.5+rev1.prod
v2.71.5+rev1.dev
v2.71.3+rev1.prod
v2.71.3+rev1.devThen, find the latest development version (.dev) version (in our example, we'll take v2.80.5+rev1.dev).
Run the command
balena os download raspberrypi4-64 --output scitizen-os-dev.img --version v2.80.5+rev1.devExample of output
Getting device operating system for raspberrypi4-64
Downloading Device OS 2.80.5+rev1.dev [========================] 100% eta 0s
The image was downloaded successfullyRun the command
sudo balena local configure scitizen-os-dev.imgExample of output
? Network SSID My_Wifi_Ssid
? Network Key super_secret_wifi_password
? Do you want to set advanced settings? Yes
? Device Hostname scitizen
? Do you want to enable persistent logging? No
Done!In Device Hostname, fill in scitizen.
If you need Wi-Fi, you can also set it up here.
Run the command
balena util available-drivesExample of output
DEVICE SIZE DESCRIPTION
/dev/disk2 31.9 GB Generic STORAGE DEVICE MediaIn our example, the drive is /dev/disk2.
Run the command
sudo balena local flash scitizen-os-dev.img --drive /dev/disk2Example of output
? This will erase the selected drive. Are you sure? Yes
Flashing [========================] 100% eta 0s
Validating [========================] 100% eta 0s
Run the command
sudo balena scanExample of output
Scanning for local balenaOS devices... Reporting scan results
-
host: scitizen.local
address: 192.168.0.25
osVariant: development
dockerInfo:
Containers: 1
ContainersRunning: 1
ContainersPaused: 0
ContainersStopped: 0
Images: 2
Driver: overlay2
SystemTime: 2021-08-25T11:57:56.229479306Z
KernelVersion: 5.4.83-v8
OperatingSystem: balenaOS 2.80.5+rev1
Architecture: aarch64
dockerVersion:
Version: 19.03.18
ApiVersion: 1.40In our example, the device hostname is scitizen.local.
Run the command
balena push scitizen.localExample of output
[Info] Starting build on device 192.168.0.25
[Build] [agent] [==================================================>] 100.0MB/100.0MB
[Build] [api] [==================================================>] 100.0MB/100.0MB
[Build] [app] [==================================================>] 100.0MB/100.0MB
[Build] [wifi] [==================================================>] 100.0MB/100.0MB
[Build] [worker] [==================================================>] 100.0MB/100.0MB
[Info] Streaming device logs...
[Live] Watching for file changes...
[Live] Waiting for device state to settle...
[Live] Device state settled
[Logs] [1/1/2021, 12:00:00] [app] Hello World!
...
[Logs] [1/1/2021, 14:00:00] [app] Goodbye World!Congratulations 🎉! You now have a live session where every changes you apply on the code will be build and pushed to your device.
To connect to the Host OS, run the command
balena ssh scitizen.localTo connect to a specific service, run the command
balena ssh scitizen.local <service>Example: balena ssh scitizen.local app
It is also possible to contribute to Scitizen even if you do not have access to a physical device like a Raspberry Pi.
We will use a container image to emulate the Host OS.
In order to develop without a local device, follow these steps 👇
Fork this repository to your own GitHub account and then clone it to your local device.
You can find the installation instructions here.
Run the command
docker run \
--name scitizen_os \
--detach \
--interactive \
--tty \
--privileged \
--network host \
--restart always \
--tmpfs /run,/run/lock,/tmp,/var/lib/journal,/sys/fs/cgroup/systemd \
--volume /lib/modules:/lib/modules:ro \
ghcr.io/pcorbel/scitizen/development-os:latestRun the command
balena scanExample of output
Scanning for local balenaOS devices... Reporting scan results
-
host: f88f3cb.local
address: 10.128.0.3
osVariant: development
dockerInfo:
Containers: 1
ContainersRunning: 1
ContainersPaused: 0
ContainersStopped: 0
Images: 2
Driver: overlay2
SystemTime: 2021-09-15T12:42:14.121444495Z
KernelVersion: 4.19.0-17-cloud-amd64
OperatingSystem: balenaOS 2.83.18+rev1 (containerized)
Architecture: x86_64
dockerVersion:
Version: 19.03.24
ApiVersion: 1.40In our example, the device address is 10.128.0.3.
Run the command
balena push 10.128.0.3Example of output
[Info] Starting build on device 10.128.0.3
[Build] [agent] [==================================================>] 100.0MB/100.0MB
[Build] [api] [==================================================>] 100.0MB/100.0MB
[Build] [app] [==================================================>] 100.0MB/100.0MB
[Build] [wifi] [==================================================>] 100.0MB/100.0MB
[Build] [worker] [==================================================>] 100.0MB/100.0MB
[Info] Streaming device logs...
[Live] Watching for file changes...
[Live] Waiting for device state to settle...
[Live] Device state settled
[Logs] [1/1/2021, 12:00:00] [app] Hello World!
...
[Logs] [1/1/2021, 14:00:00] [app] Goodbye World!Congratulations 🎉! You now have a live session where every changes you apply on the code will be build and pushed to your device.
When you're done making changes and you'd like to propose them for review, open your PR (pull request).
Once you submit your PR, others from the Scitizen community will review it with you. After that, we may have questions, check back on your PR to keep up with the conversation. Did you have an issue, like a merge conflict? Check out a git tutorial on how to resolve merge conflicts and other issues.
Congratulations! The whole Scitizen community thanks you 🙏!
Once your PR is merged, you will be proudly listed as a contributor in the contributor chart 🏅.