diff --git a/Source/Meadow.Core.sln b/Source/Meadow.Core.sln index 3f099b99..306b3aec 100644 --- a/Source/Meadow.Core.sln +++ b/Source/Meadow.Core.sln @@ -17,6 +17,7 @@ EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "linux", "linux", "{B187C117-A16E-4A75-B862-3CA7DCA464B8}" ProjectSection(SolutionItems) = preProject implementations\linux\beaglebone.md = implementations\linux\beaglebone.md + implementations\linux\raspberrypi.md = implementations\linux\raspberrypi.md implementations\linux\README.md = implementations\linux\README.md EndProjectSection EndProject diff --git a/Source/implementations/linux/README.md b/Source/implementations/linux/README.md index 98debb39..87c5aeef 100644 --- a/Source/implementations/linux/README.md +++ b/Source/implementations/linux/README.md @@ -11,119 +11,35 @@ Wilderness Labs Meadow.Linux is a .NET Framework for running IoT applications on ## Supported Platforms and Distributions -Currently tested platforms and distributions: +Linux Embedded Hardware is a broad space and we've made efforts to test support on a broad number of devices. because Meadow is modular and interface-based, adding new platform support is generally simple, requiring only a few days to port and test with hardware. -| Hardware | Distro | Meadow.Core Version tested | -| :---: | :---: | :---: | -| Raspberry Pi 4 | Raspberry Pi OS | Beta 6.2 | -| Raspberry Pi Zero 2 W | Raspberry Pi OS | Beta 6.2 | -| Jetson Nano | Ubuntu 20.04 | Beta 6.2 | -| Jetson Xavier AGX | Ubuntu 18.04 | RC-2 | -| KRTKL Snickerdoodle Black | Ubuntu 20.04 | RC-1 | -| AMD64 Ubuntu 20.04 under WSL2 | Ubuntu 20.04 | RC-1 | +The table below shows the platforms we have done at least some work on and to what degree we have tested subsystems. -## License - -Apache 2.0 - -See [LICENSE File](/LICENSE) - -## Assumptions - -For this documentation, we assume you are developing your application code on a machine *separate* from your target hardware. You can certainly develop and compile your application directly on your target hardware, but the possible variations and permutations make documenting the process more difficult. If you are new to .NET development on IoT devices, we recommend starting with a separate development machine first. - -## Prepare Your Target Hardware - -`Meadow.Linux` runs applications using the .NET 6.0 Core Runtime, so you must install it on the target. - -### Install .NET 7.0 - -Follow the instructions based on your distro: - -https://docs.microsoft.com/en-us/dotnet/core/install/linux - -```console -$ dotnet --list-runtimes -Microsoft.NETCore.App 7.0.2 [/opt/dotnet/shared/Microsoft.NETCore.App] -``` - -### Enable Hardware Access - -Different platforms will have different rules for enabling application access to hardware devices such as GPIO, SPI and I2C. Consult your platform documentation for specifics, but as an example Raspberry Pi OS requires that you run `raspi-config` to enable the peripherals you want, and *additionally* add your user to specific groups for the peripherals. If you get permissions errors while first running your application, this is the place to start looking. - -## Develop your Application +| Platform | OS Tested | GPIO | I2C | SPI | ADC | UART | PWM | +| --- | --- | --- | --- | --- | --- | --- | +| Raspberry Pi 3b+ | Rasberry Pi OS xxx 64-bit Lite | X | X | X | - | U | O | +| Raspberry Pi 4 | Rasberry Pi OS xxx 64-bit Lite | X | X | X | - | U | O | +| Raspberry Pi 5 | Rasberry Pi OS xxx 64-bit Lite | X | X | X | - | X | O | +| Raspberry Pi Zero 2 W | Rasberry Pi OS Lite 64 (kernel 6.6.20+rpt-rpi-v8, Debian Bookworm 1:6.6.20-1+rpt1) | X | X | X | - | X | O | +| BeagleBone Black | Debian Bullseye (kernel 5.10.168-ti-r72) | X | X | X | X | O | X | +| NVIDIA Jetson Xavier Nano | Ubuntu 18.04 | X | O | O | - | O | O | +| NVIDIA Jetson Xavier AGX | Ubuntu 18.04 | X | X | U | - | O | O | +| krtkl Snickerdoodle Black | Ubuntu 20.04 | X | O | O | - | O | O | +| AMD64 Ubuntu 20.04 under WSL2 | Ubuntu 20.04 | - | - | - | - | U | - | -- Create a .NET 7 Core Application Project -- Add NuGet references to Meadow.Linux and any other requirements (e.g Meadow.Foundation and peripheral drivers) -- Develop/Compile +X: Implemented and tested +U: Implemented but untested +O: Not implemented/Not Tested +-: Not supported by hardware -## Deploying +## Platform-Specific Instructions and Details -When you are ready to run your application you will need to copy it, and all dependencies, to the target device. +### [BeagleBone Black](beaglebone.md) +### [Raspberry Pi](raspberrypi.md) -The simplest, most reliable way to collect all of those binaries is by using `dotnet publish`. - -For example, the `Bme280_Sample` in this repo can be published to a local folder like this: - -```console -C:\repos\wilderness\Meadow.Linux\src\samples\Bme280_Sample>dotnet publish -c Release -o publish -Microsoft (R) Build Engine version 17.2.0+41abc5629 for .NET -Copyright (C) Microsoft Corporation. All rights reserved. - - Determining projects to restore... - All projects are up-to-date for restore. - Meadow.Linux -> C:\repos\wilderness\Meadow.Linux\src\lib\bin\Release\netstandard2.1\Meadow.Linux.dll - Bme280_Sample -> C:\repos\wilderness\Meadow.Linux\src\samples\Bme280_Sample\bin\Release\net7.0\App.dll - Bme280_Sample -> C:\repos\wilderness\Meadow.Linux\src\samples\Bme280_Sample\publish\ -``` - -The output folder contains all of the files and assemblies you need to copy to your target hardware. - -Now use a tool such as SCP to copy all of these files to a folder on you target hardware. - -[add example command / winscp sceen cap] - -[todo: this is a note from my previous work, check if App.deps is a problem] -- Copy over your application binaries and `App.runtimeconfig.json`. Do *not* copy over App.deps.json - -Here's an example of all of the binaries for the Bme280_Sample aaplication after deployment to a target Raspberry Pi: - -```console -$ ls -al -total 472 -drwxr-xr-x 2 pi pi 4096 Nov 7 17:56 . -drwxr-xr-x 16 pi pi 4096 Nov 7 17:55 .. --rw-r--r-- 1 pi pi 7680 Nov 7 18:09 App.dll --rw-r--r-- 1 pi pi 147 Nov 7 17:55 App.runtimeconfig.json --rw-r--r-- 1 pi pi 17920 Nov 7 17:58 Bme280.dll --rw-r--r-- 1 pi pi 69632 Nov 7 17:23 Meadow.Contracts.dll --rw-r--r-- 1 pi pi 127488 Nov 7 17:23 Meadow.dll --rw-r--r-- 1 pi pi 111104 Nov 7 17:23 Meadow.Foundation.dll --rw-r--r-- 1 pi pi 38400 Nov 7 17:23 Meadow.Linux.dll --rw-r--r-- 1 pi pi 83968 Nov 7 17:23 Meadow.Units.dll -``` - -## Running - -Starting with the `RC1.0` release, Meadow now has a defined lifecycle. This is imposed to allow automated application shutdown by the OtA update service. What this means, practically, is that your Meadow.Linux application must define an entry point in your `App` implementation and and manually start the MeadowOS stack. - -```console -public class MeadowApp : App -{ - public static async Task Main(string[] _) - { - await MeadowOS.Start(); - } - ... -} -``` +## License -Then launch the application using `dotnet` +Apache 2.0 -```console -$ dotnet MyAppAssembly.dll -``` - -## Work in Progress +See [LICENSE File](/LICENSE) -`Meadow.Linux` is currently an *Beta* product with several core features that are not yet implemented. Details are available in the [Issues Tab](https://github.com/WildernessLabs/Meadow.Linux/issues) and the source. diff --git a/Source/implementations/linux/raspberrypi.md b/Source/implementations/linux/raspberrypi.md new file mode 100644 index 00000000..42de673a --- /dev/null +++ b/Source/implementations/linux/raspberrypi.md @@ -0,0 +1,165 @@ +# Meadow Linux on Raspberry Pi + +## Assumptions + +For this documentation, we assume you are developing your application code on a machine *separate* from your target hardware. You can certainly develop and compile your application directly on your target hardware, but the possible variations and permutations make documenting the process more difficult. If you are new to .NET development on IoT devices, we recommend starting with a separate development machine first. + +## Prepare Your Target Hardware + +`Meadow.Linux` runs applications using the .NET 8.0 Core Runtime, so you must install it on the target. + +### Install .NET + +Create and edit a new shell script +``` +nano raspi-dotnet.sh +``` + +``` +#!/bin/bash + +add_to_bashrc() { + local string="$1" + if ! grep -q "$string" "$HOME/.bashrc"; then + echo "$string" >> $HOME/.bashrc + fi +} + +wget --inet4-only https://dot.net/v1/dotnet-install.sh -O - | bash /dev/stdin --version latest +add_to_bashrc "export DOTNET_ROOT=\$HOME/.dotnet" +add_to_bashrc "export PATH=\$PATH:\$HOME/.dotnet" +``` + + + +List the local files + +``` +ls -l +``` +Which gives an output like this: +``` +total 4 +-rw-r--r-- 1 pi pi 364 May 28 20:22 raspi-dotnet.sh +``` + +Make the shell script executable + +``` +chmod +x raspi-dotnet.sh +``` +The file list will change +``` +ls -l +total 4 +-rwxr-xr-x 1 pi pi 364 May 28 20:22 raspi-dotnet.sh +``` + +Execute the newly-created script + +``` +./raspi-dotnet.sh +``` + +This takes a long time, like over 5 minutes long. Be patient. In the end you should see something like + +``` +dotnet-install: Installation finished successfully. +``` + +Now re-load your environment and verify the install + +``` +source ~/.bashrc +dotnet --version +``` +This wll give the installed .NET version. +``` +8.0.301 +``` + +### Enable Hardware Things + +Now you have to enable access to things like the hardware busses and GPIO + +``` +sudo raspi-config +``` + +### Enable Hardware Access + +Use `raspi-config` to enable I2C and SPI on the platform. + +## Develop your Application + +- Create a .NET 8 Core Application Project +- Add NuGet references to Meadow.Linux and any other requirements (e.g Meadow.Foundation and peripheral drivers) +- Develop/Compile + +## Deploying + +When you are ready to run your application you will need to copy it, and all dependencies, to the target device. + +The simplest, most reliable way to collect all of those binaries is by using `dotnet publish`. + +For example, the `Bme280_Sample` in this repo can be published to a local folder like this: + +```console +C:\repos\wilderness\Meadow.Linux\src\samples\Bme280_Sample>dotnet publish -c Release -o publish +Microsoft (R) Build Engine version 17.2.0+41abc5629 for .NET +Copyright (C) Microsoft Corporation. All rights reserved. + + Determining projects to restore... + All projects are up-to-date for restore. + Meadow.Linux -> C:\repos\wilderness\Meadow.Linux\src\lib\bin\Release\netstandard2.1\Meadow.Linux.dll + Bme280_Sample -> C:\repos\wilderness\Meadow.Linux\src\samples\Bme280_Sample\bin\Release\net7.0\App.dll + Bme280_Sample -> C:\repos\wilderness\Meadow.Linux\src\samples\Bme280_Sample\publish\ +``` + +The output folder contains all of the files and assemblies you need to copy to your target hardware. + +Now use a tool such as SCP to copy all of these files to a folder on you target hardware. + +[add example command / winscp sceen cap] + +[todo: this is a note from my previous work, check if App.deps is a problem] +- Copy over your application binaries and `App.runtimeconfig.json`. Do *not* copy over App.deps.json + +Here's an example of all of the binaries for the Bme280_Sample aaplication after deployment to a target Raspberry Pi: + +```console +$ ls -al +total 472 +drwxr-xr-x 2 pi pi 4096 Nov 7 17:56 . +drwxr-xr-x 16 pi pi 4096 Nov 7 17:55 .. +-rw-r--r-- 1 pi pi 7680 Nov 7 18:09 App.dll +-rw-r--r-- 1 pi pi 147 Nov 7 17:55 App.runtimeconfig.json +-rw-r--r-- 1 pi pi 17920 Nov 7 17:58 Bme280.dll +-rw-r--r-- 1 pi pi 69632 Nov 7 17:23 Meadow.Contracts.dll +-rw-r--r-- 1 pi pi 127488 Nov 7 17:23 Meadow.dll +-rw-r--r-- 1 pi pi 111104 Nov 7 17:23 Meadow.Foundation.dll +-rw-r--r-- 1 pi pi 38400 Nov 7 17:23 Meadow.Linux.dll +-rw-r--r-- 1 pi pi 83968 Nov 7 17:23 Meadow.Units.dll +``` + +## Running + +Starting with the `RC1.0` release, Meadow now has a defined lifecycle. This is imposed to allow automated application shutdown by the OtA update service. What this means, practically, is that your Meadow.Linux application must define an entry point in your `App` implementation and and manually start the MeadowOS stack. + +```console +public class MeadowApp : App +{ + public static async Task Main(string[] _) + { + await MeadowOS.Start(); + } + ... +} +``` + +Then launch the application using `dotnet` + +```console +$ dotnet MyAppAssembly.dll +``` + \ No newline at end of file