Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/device-tree-overlay/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,15 +56,15 @@ The device tree overlay packages must specify the kernel drivers for the new dev

:::tip

See the [How Firmware is Built article](https://documentation.onioniot.com/firmware/how-to-build-firmware)[ ](https://documentation.onioniot.com/firmware/how-to-build-firmware) for more information on the details of building firmware.
See the [How Firmware is Built article](https://documentation.onioniot.com/firmware/how-to-build-firmware) for more information on the details of building firmware.

:::

## How a Device Tree Overlay Package works on the device

Use the `opkg` package manager to install a software package that features a compiled device tree overlay binary. After a reboot, the device tree overlay will be loaded, and the kernel will be made aware of a new device.

The kernel will load drivers to enable support for the device.
The kernel will load drivers to enable support for the device.

## How to create custom Device Tree Overlay packages

Expand Down
6 changes: 3 additions & 3 deletions docs/device-tree-overlay/one-wire-devices.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,10 @@ For more information on using One-Wire, see the following [One-Wire article](../

The Device Tree Overlay package is part of the `onion-dt-overlay` package.

The DTS fragment that enables this functionality can be found in the OnionIoT/OpenWRT-Packages GitHub repository at: https://github.com/OnionIoT/OpenWRT-Packages/blob/openwrt-23.05/onion-dt-overlay/src/w1-gpio.dts
The DTS fragment that enables this functionality can be found in the OnionIoT/OpenWRT-Packages GitHub repository at: [https://github.com/OnionIoT/OpenWRT-Packages/blob/openwrt-23.05/onion-dt-overlay/src/w1-gpio.dts](https://github.com/OnionIoT/OpenWRT-Packages/blob/openwrt-23.05/onion-dt-overlay/src/w1-gpio.dts)
<!-- TODO: update above with OPENWRT_VERSION variable -->

The package definition can be found at: https://github.com/OnionIoT/OpenWRT-Packages/blob/openwrt-23.05/onion-dt-overlay/Makefile
The package definition can be found at: [https://github.com/OnionIoT/OpenWRT-Packages/blob/openwrt-23.05/onion-dt-overlay/Makefile](https://github.com/OnionIoT/OpenWRT-Packages/blob/openwrt-23.05/onion-dt-overlay/Makefile)
<!-- TODO: update above with OPENWRT_VERSION variable -->

<GiscusDocComment />
<GiscusDocComment />
6 changes: 3 additions & 3 deletions docs/device-tree-overlay/software-spi.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,12 +48,12 @@ For further instruction on using the SPI Bus see the [SPI article](../hardware-i

## Source Code

The DTS fragment that enables the SPI Bus functionality can be found in the OnionIoT/OpenWRT-Packages GitHub repository at: https://github.com/OnionIoT/OpenWRT-Packages/blob/openwrt-23.05/onion-dt-overlay/src/sw-spi.dts
The DTS fragment that enables the SPI Bus functionality can be found in the OnionIoT/OpenWRT-Packages GitHub repository at: [https://github.com/OnionIoT/OpenWRT-Packages/blob/openwrt-23.05/onion-dt-overlay/src/sw-spi.dts](https://github.com/OnionIoT/OpenWRT-Packages/blob/openwrt-23.05/onion-dt-overlay/src/sw-spi.dts)
<!-- TODO: update above with OPENWRT_VERSION variable -->

The package definition can be found at: https://github.com/OnionIoT/OpenWRT-Packages/blob/openwrt-23.05/onion-dt-overlay/Makefile
The package definition can be found at: [https://github.com/OnionIoT/OpenWRT-Packages/blob/openwrt-23.05/onion-dt-overlay/Makefile](https://github.com/OnionIoT/OpenWRT-Packages/blob/openwrt-23.05/onion-dt-overlay/Makefile)
<!-- TODO: update above with OPENWRT_VERSION variable -->

It is part of the `onion-dt-overlay` package.

<GiscusDocComment />
<GiscusDocComment />
2 changes: 1 addition & 1 deletion docs/feedback.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,4 @@ There are issue templates for Bug Reports and Improvement Suggestions/Feature Re

If there's something unclear or missing in this documentation, or if it can be improved in some way, create an issue in the [OnionIoT/documentation GitHub Repo](https://github.com/OnionIoT/documentation) and explain what could be better documented.

If there's a specific edit you'd like to make to one of these documentation pages, click the **Edit this page** and you'll be taken to the corresponding file on GitHub. We welcome all Pull Requests.
If there's a specific edit you'd like to make to one of these documentation pages, click the **Edit this page** and you'll be taken to the corresponding file on GitHub. We welcome all Pull Requests.
23 changes: 11 additions & 12 deletions docs/firmware/how-onion-builds-firmware.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,8 +71,8 @@ Onion's custom OpenWRT Build System is compiled by our CI system and the output

The Build System output is available on our website:

- Default packages - http://downloads.onioniot.com/releases/23.05.3/packages/mipsel_24kc/ <!-- TODO: update with OPENWRT_RELEASE variable -->
- Compiled versions of the SDK and Image Builder - http://downloads.onioniot.com/releases/23.05.3/targets/ramips/mt76x8/ <!-- TODO: update with OPENWRT_RELEASE variable -->
- Default packages - [http://downloads.onioniot.com/releases/23.05.3/packages/mipsel_24kc/](http://downloads.onioniot.com/releases/23.05.3/packages/mipsel_24kc/) <!-- TODO: update with OPENWRT_RELEASE variable -->
- Compiled versions of the SDK and Image Builder - [http://downloads.onioniot.com/releases/23.05.3/targets/ramips/mt76x8/](http://downloads.onioniot.com/releases/23.05.3/targets/ramips/mt76x8/) <!-- TODO: update with OPENWRT_RELEASE variable -->

:::note

Expand All @@ -84,7 +84,7 @@ The release directory also has firmware images. You can safely ignore these, as

The second process uses the Onion-customized OpenWRT SDK and Image Builder to build and release Onion's custom software packages and custom firmware images.

This process is automatically started by our CI system whenever there is a release created in the `OnionIoT/OpenWRT-Packages` GitHub repository.
This process is automatically started by our CI system whenever there is a release created in the `OnionIoT/OpenWRT-Packages` GitHub repository.

## Process 2 - Step A: Onion-customized OpenWRT SDK

Expand All @@ -94,17 +94,17 @@ In step A of the second process, we use the Onion-customized OpenWRT SDK to buil

One of the core tenets of Onion device firmware is to localize all customizations in packages. This makes it easy to port the changes to new releases and reduces the number of "fronts" that must be maintained.

Our goal is to create custom packages that bring value to our customers, by making them easy to use or by adding more functionality. Examples of this are the **default network configuration** and the **gpio muxing utility**.
Our goal is to create custom packages that bring value to our users, by making them easy to use or by adding more functionality. Examples of this are the **default network configuration** and the **gpio muxing utility**.

The SDK has a wrapper around it, which makes it easier to interact with the SDK. By default, it uses the Onion-customized OpenWRT SDK, and compiles packages from the `openwrt-23.05` branch of the `OnionIoT/OpenWRT-Packages` GitHub repository.
The SDK has a wrapper around it, which makes it easier to interact with the SDK. By default, it uses the Onion-customized OpenWRT SDK, and compiles packages from the `openwrt-23.05` branch of the `OnionIoT/OpenWRT-Packages` GitHub repository.
<!-- TODO: update above with OPENWRT_VERSION variable -->

### Where is the source code?

The source code can be found on GitHub: https://github.com/OnionIoT/OpenWRT-Packages/tree/openwrt-23.05
The source code can be found on GitHub: [https://github.com/OnionIoT/OpenWRT-Packages/tree/openwrt-23.05](https://github.com/OnionIoT/OpenWRT-Packages/tree/openwrt-23.05)
<!-- TODO: update above with OPENWRT_VERSION variable -->

The `openwrt-sdk-wrapper` repo easily and quickly compiles packages using the Onion OpenWRT SDK: https://github.com/OnionIoT/openwrt-sdk-wrapper
The `openwrt-sdk-wrapper` repo easily and quickly compiles packages using the Onion OpenWRT SDK: [https://github.com/OnionIoT/openwrt-sdk-wrapper](https://github.com/OnionIoT/openwrt-sdk-wrapper)

The `profile` config file defines which SDK to use, the version of the SDK, the package feed, and which packages from the package feed to compile.

Expand All @@ -118,9 +118,9 @@ See the [Compile a Package article](../packages/compile-package) for details on

### Where is the package output?

Our CI system uses Onion's custom OpenWRT SDK to compile packages and the output is placed in the repo section of our website.
Our CI system uses Onion's custom OpenWRT SDK to compile packages and the output is placed in the repo section of our website.

The compiled packages can be found at: http://repo.onioniot.com/omega2/packages/openwrt-23.05.3/ <!-- TODO: update above with OPENWRT_RELEASE variable -->
The compiled packages can be found at: [http://repo.onioniot.com/omega2/packages/openwrt-23.05.3/](http://repo.onioniot.com/omega2/packages/openwrt-23.05.3/) <!-- TODO: update above with OPENWRT_RELEASE variable -->

## Process 2 - Step B: Onion-customized OpenWRT Image Builder

Expand All @@ -133,7 +133,7 @@ The compiled firmware images include:
- The default packages.
- Onion's custom packages.

We use a wrapper to interact with the OpenWRT Image Builder, which makes it easy to build firmware. By default, the wrapper is set up to use the Onion-customized Image Builder that is built in the first process.
We use a wrapper to interact with the OpenWRT Image Builder, which makes it easy to build firmware. By default, the wrapper is set up to use the Onion-customized Image Builder that is built in the first process.

**Note:** You can instead use the vanilla Image Builder from OpenWRT to build firmware.

Expand All @@ -155,8 +155,7 @@ See the [How to Build Custom Firmware article](./how-to-build-firmware) for deta

Our CI system uses Onion's custom OpenWRT Image Builder to compile firmware images and the output is placed in the repo section of our website.

The compiled firmware images can be found at: http://repo.onioniot.com/omega2/images/openwrt-23.05/
The compiled firmware images can be found at: [http://repo.onioniot.com/omega2/images/openwrt-23.05/](http://repo.onioniot.com/omega2/images/openwrt-23.05/)
<!-- TODO: update above with OPENWRT_VERSION variable -->

<GiscusDocComment />

25 changes: 12 additions & 13 deletions docs/firmware/how-to-build-firmware.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ In the first part of this article, we define firmware and custom firmware. We di

### What is firmware?

Before we discuss custom firmware, we need to define what firmware is. Firmware is a software program that is embedded in hardware devices. It is like an operating system, such as macOS or Windows, installed on a computer. When the device boots up, the firmware acts as the operating system for a Linux device. It performs all control, monitoring, and data manipulation functions.
Before we discuss custom firmware, we need to define what firmware is. Firmware is a software program that is embedded in hardware devices. It is like an operating system, such as macOS or Windows, installed on a computer. When the device boots up, the firmware acts as the operating system for a Linux device. It performs all control, monitoring, and data manipulation functions.

Firmware is made by combining packages with a Linux kernel to create a firmware image. This image includes key components like the Linux kernel, WiFi drivers, text editor, and standard packages for enhanced usability.

Expand Down Expand Up @@ -42,23 +42,23 @@ The firmware image can include both default software packages and custom package

### Benefits of custom firmware

- Speeds up production time – a single firmware image can be flashed at the time of manufacture that features the Omega2 module and enables the customer's specific use case.
- Speeds up production time – a single firmware image can be flashed at the time of manufacture that features the Omega2 module and enables the user's specific use case.
- Better user experience in case of a factory reset - When a factory reset is performed, the device will reset to the default state of the firmware that was last flashed.
- **Custom firmware** - the device will run the customer's firmware with default settings after a factory reset.
- **Onion firmware with additional customizations added later by customer** - the device will run the Onion firmware after a factory reset without the customizations and no support for the customer's use case.
- **Custom firmware** - the device will run the user's firmware with default settings after a factory reset.
- **Onion firmware with additional customizations added later by user** - the device will run the Onion firmware after a factory reset without the customizations and no support for the user's use case.

## Recommended build method

There are a few different methods to build firmware images. Onion recommends using the OpenWRT Image Builder to build firmware images.
There are a few different methods to build firmware images. Onion recommends using the OpenWRT Image Builder to build firmware images.

The Image Builder is a pre-compiled environment for creating custom images without the need to compile them from source. It downloads pre-compiled software packages and integrates them into a single flashable image ([reference](https://openwrt.org/docs/guide-user/additional-software/imagebuilder#using_the_image_builder)).

Why is the Image Builder favored over other methods:

- Image Builder creates a firmware image in minutes as opposed to several hours using the OpenWRT build system.
- Allows for faster iteration during the development cycle.
- Allows for faster iteration during the development cycle.
- Promotes encapsulation of image customizations into packages.
- Better maintainability as opposed to a mix of package customizations and file additions.
- Better maintainability as opposed to a mix of package customizations and file additions.

Onion's Image Builder Wrapper makes use of the OpenWRT image builder and a set of supporting scripts and config files to make image creation straightforward, fast, and programmatic.

Expand Down Expand Up @@ -98,17 +98,17 @@ import InstallDeps from './_install-deps.mdx';

#### 3. Clone the OnionIoT/openwrt-imagebuilder-wrapper repo

This repository is set up to build OpenWRT firmware for the Onion Omega2 and Omega2+.
This repository is set up to build OpenWRT firmware for the Onion Omega2 and Omega2+.

To clone the openwrt-imagebuilder-wrapper repo, issue the following command:

```Shell
git clone https://github.com/OnionIoT/openwrt-imagebuilder-wrapper.git
```
```

### Customizing the firmware image

The firmware image specifications are defined in the `profile` configuration file.
The firmware image specifications are defined in the `profile` configuration file.

#### Customization

Expand Down Expand Up @@ -186,15 +186,14 @@ The build should take less than 5 minutes.

#### 2. Locate the compiled firmware image

Compiled firmware images are in the `output` directory.
Compiled firmware images are in the `output` directory.

The firmware images are named based on the device model name, the OpenWRT version number specified in the `profile` file, and the date of the build: `<BUILD_MODEL>-<OPENWRT_VERSION>-<BUILD_DATE>.bin` .

For example:

For an Omega2+ device, with OPENWRT_VERSION="23.05.3" set in the `profile` config file and built on May 31, 2024. The firmware image name will be `onion_omega2p-23.05.3-20240531.bin`.
For an Omega2+ device, with OPENWRT_VERSION="23.05.3" set in the `profile` config file and built on May 31, 2024. The firmware image name will be `onion_omega2p-23.05.3-20240531.bin`.

<!-- NOTE: Ok to keep OpenWRT release numbers hard-coded in this section -->

<GiscusDocComment />

8 changes: 4 additions & 4 deletions docs/firmware/installing-firmware.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ title: Installing the New Firmware

import { GiscusDocComment } from '/src/components/GiscusComment';

> This firmware doesn't include the `oupgrade` utility, so we'll need to manually install the firmware. The procedure is very similar to the [Manual Firmware Installation instructions in the Onion Documentation](http://docs.onion.io/omega2-docs/manual-firmware-installation.html).
> This firmware doesn't include the `oupgrade` utility, so we'll need to manually install the firmware. The procedure is very similar to the [Manual Firmware Installation instructions in the Onion Documentation](http://docs.onion.io/omega2-docs/manual-firmware-installation.html).

The new firmware can be found online at http://repo.onioniot.com/omega2/images/openwrt-23.05/ <!-- TODO: update with OPENWRT_VERSION variable -->
The new firmware can be found online at [http://repo.onioniot.com/omega2/images/openwrt-23.05/](http://repo.onioniot.com/omega2/images/openwrt-23.05/) <!-- TODO: update with OPENWRT_VERSION variable -->

The firmware images are named according to this syntax: `<DEVICE-NAME>-<OPENWRT-VERSION>-<BUILD-DATE>.bin`

Expand All @@ -20,7 +20,7 @@ So `onion_omega2p-23.05.3-20240807.bin` is: <!-- TODO: update with ONION_FW_VERS

Before you install firmware to your device, you'll need to decide which firmware image to install.

To start, use a browser to navigate to http://repo.onioniot.com/omega2/images/openwrt-23.05/ <!-- TODO: update with OPENWRT_VERSION variable -->
To start, use a browser to navigate to [http://repo.onioniot.com/omega2/images/openwrt-23.05/](http://repo.onioniot.com/omega2/images/openwrt-23.05/) <!-- TODO: update with OPENWRT_VERSION variable -->

Next, you'll need to find the firmware for your device:

Expand Down Expand Up @@ -59,4 +59,4 @@ From time to time, we'll be releasing new firmware images with various updates.

**WARNING**: because `sysupgrade` is run with the `-n` option, **everything that's currently on the device will be erased when the firwmare is updated.** So all new files and changes on your device will be deleted as part of the upgrade process, and you will start with a fresh device.

<GiscusDocComment />
<GiscusDocComment />
4 changes: 2 additions & 2 deletions docs/hardware-interfaces/ethernet.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ See the [Omega2S hardware design guide](https://github.com/OnionIoT/Omega2/blob/

## Software

The Ethernet port can be configured to be a client or a Dynamic Host Configuration Protocol (DHCP) host. It is set to client mode by default.
The Ethernet port can be configured to be a client or a Dynamic Host Configuration Protocol (DHCP) host. It is set to client mode by default.

For more information on Ethernet networking, see the [Ethernet networking article](../networking/ethernet).

<GiscusDocComment />
<GiscusDocComment />
6 changes: 2 additions & 4 deletions docs/hardware-interfaces/external-storage.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,13 @@
title: External Storage
---

# External Storage

This firmware includes the kernel modules required for external USB and SD Card storage - including support for a variety of filesystems.
This firmware includes the kernel modules required for external USB and SD Card storage - including support for a variety of filesystems.

## USB

Plug in a USB drive and you’ll see a message like:

```
```shell
[ 1704.267974] usb 1-1: new high-speed USB device number 2 using ehci-platform
[ 1704.479893] usb-storage 1-1:1.0: USB Mass Storage device detected
[ 1704.502029] scsi host0: usb-storage 1-1:1.0
Expand Down
4 changes: 1 addition & 3 deletions docs/hardware-interfaces/gpio.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ See detailed explanation of [**Multiplexed Pins**](./pin-multiplexing.md).

## Software

The GPIOs can be accessed through the GPIO sysfs interface, see the [**documentation**](https://www.kernel.org/doc/Documentation/gpio/sysfs.txt) for details.
The GPIOs can be accessed through the GPIO sysfs interface, see the [**documentation**](https://www.kernel.org/doc/Documentation/gpio/sysfs.txt) for details.

:::info
The GPIO sysfs interface is deprecated but is currently the best option for userspace GPIO access. More context is available in this post by [**Luz on the Onion Community**](https://community.onion.io/topic/4892/can-bus-using-mcp2515-with-omega2/13).
Expand All @@ -65,7 +65,6 @@ This only applies to Onion's OpenWRT 22.03 firmware releases

:::


In earlier 22.03 releases of the Onion Omega2 firmmware, the GPIO numbering in Linux did not match the device's actual GPIO numbers. This was due to changes in the kernel around GPIO handling.

- GPIO 0 - 31 ⇒ GPIO 480 - 511 (GPIO n + 480)
Expand All @@ -79,5 +78,4 @@ In earlier 22.03 releases of the Onion Omega2 firmmware, the GPIO numbering in L

<!-- should add an example here -->


<GiscusDocComment />
Loading