Skip to content

Commit

Permalink
Updated the README file.
Browse files Browse the repository at this point in the history
  • Loading branch information
matthew-holder-revvity committed Aug 31, 2024
1 parent 13c970c commit 96c9864
Showing 1 changed file with 48 additions and 77 deletions.
125 changes: 48 additions & 77 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,12 @@ A/V switch and monitor controller
Copyright ©2019-2020 Matthew Holder

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later
version.
License as published by the Free Software Foundation, either version 3 of the License, or (at your option)
any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.

You should have received a copy of the GNU General Public License along with this program. If not, see
<https://www.gnu.org/licenses/>.
Expand All @@ -24,47 +25,45 @@ You should have received a copy of the GNU General Public License along with thi

To install BridgeCmdr on the Raspberry Pi, all you need do is download the
[latest release](https://github.com/6XGate/bridgecmdr/releases), grant
the execution permission and run it. It may ask you to integrate the
with the system to moving itself to common location and adding a
desktop entry.

It is best not to use BridgeCmdr with any tools such as `appimagelauncher`.
the execution permission and run it. It is recommended that you use
something like the `appimagelauncher` to better integrate it with
you desktop environment.

### System Requirements

I've only tested this software on a Raspberry Pi 3 Model B+. In general I would recommend at minimal a Raspberry Pi 3
Model B or better. Which would include every configuration of the Raspberry Pi 4 Model B. It may run on other models,
but this has not been tested.
Model B or better. Which would include every configuration of the Raspberry Pi 4 Model B. It may run on other
models, but this has not been tested.

You will also need a touchscreen, such as the official Raspberry Pi touchscreen, or a mouse and screen. You will also
need a keyboard while setting up your configuration, but it is not needed during day-to-day use.
You will want a touchscreen, such as the official Raspberry Pi touchscreen, or a mouse and screen. You will also need a
keyboard while setting up your configuration, but it is not needed during day-to-day use.

You may also need additional USB-to-serial adapters or a serial HAT. Some supported monitors and switches can be
controlled over ethernet. For those you will need an ethernet cable; and if you have more than one such device, an
ethernet hub or switch. See [Wiki](https://github.com/6XGate/bridgecmdr/wiki) for more information on how to connect to
supported monitors and switches.
controlled over ethernet. For those you will need an ethernet cable; and if you have more than one such device,
an ethernet hub or switch. See [Wiki](https://github.com/6XGate/bridgecmdr/wiki) for more information on how
to connect to supported monitors and switches.

## Tools, Frameworks, Libraries, and Assets

BridgeCmdr uses the following libraries and frameworks are a major part of its makeup.

| Framework/Library | License |
| ------------------------------------------------ | ------------------------------------------------------------------------ |
| [Electron](https://electronjs.org/) | [MIT](https://github.com/electron/electron/blob/master/LICENSE) |
| [Vue.js](https://vuejs.org/) | [MIT](https://github.com/vuejs/vue/blob/master/LICENSE) |
| [Vuetify](https://vuetifyjs.com/) | [MIT](https://github.com/vuetifyjs/vuetify/blob/master/LICENSE.md) |
| [PouchDB](https://pouchdb.com/) | [Apache 2.0](https://github.com/pouchdb/pouchdb/blob/master/LICENSE) |
| [LevelDOWN](https://github.com/Level/leveldown) | [MIT](https://github.com/Level/leveldown/blob/master/LICENSE) |
| [Vue I18n](https://vue-i18n.intlify.dev/) | [MIT](https://github.com/intlify/vue-i18n/blob/master/LICENSE) |
| [SerialPort](https://serialport.io/) | [MIT](https://github.com/serialport/node-serialport/blob/master/LICENSE) |
| [Vuelidate](https://vuelidate-next.netlify.app/) | [MIT](https://github.com/vuelidate/vuelidate/blob/next/LICENSE) |
| Framework/Library | License |
| -------------------------------------------------- | ------------------------------------------------------------------------ |
| [Electron](https://electronjs.org/) | [MIT](https://github.com/electron/electron/blob/master/LICENSE) |
| [Vue.js](https://vuejs.org/) | [MIT](https://github.com/vuejs/vue/blob/master/LICENSE) |
| [Vuetify](https://vuetifyjs.com/) | [MIT](https://github.com/vuetifyjs/vuetify/blob/master/LICENSE.md) |
| [PouchDB](https://pouchdb.com/) | [Apache 2.0](https://github.com/pouchdb/pouchdb/blob/master/LICENSE) |
| [LevelDOWN](https://github.com/Level/leveldown) | [MIT](https://github.com/Level/leveldown/blob/master/LICENSE) |
| [Vue I18n](https://vue-i18n.intlify.dev/) | [MIT](https://github.com/intlify/vue-i18n/blob/master/LICENSE) |
| [SerialPort](https://serialport.io/) | [MIT](https://github.com/serialport/node-serialport/blob/master/LICENSE) |
| [Vuelidate](https://vuelidate-next.netlify.app/) | [MIT](https://github.com/vuelidate/vuelidate/blob/next/LICENSE) |
| [zip.js](https://gildas-lormeau.github.io/zip.js/) | [BSD](https://github.com/gildas-lormeau/zip.js/blob/master/LICENSE) |

For a complete list of dependencies and other utilized libraries, see the `package.json` file.
Any other dependencies not listed above or in the package file are dependencies of those packages.
For a complete list of dependencies and other utilized libraries, see the `package.json` file. Any other dependencies
not listed above or in the package file are dependencies of those packages.

BridgeCmdr also uses the [Material Design Icons](https://pictogrammers.com/library/mdi/) SVG
graphics which are licensed under the
[Pictogrammers Free License](https://pictogrammers.com/docs/general/license/).
BridgeCmdr also uses the [Material Design Icons](https://pictogrammers.com/library/mdi/) SVG graphics which are
licensed under the [Pictogrammers Free License](https://pictogrammers.com/docs/general/license/).

## Building

Expand All @@ -85,8 +84,8 @@ The following tools or libraries are used to build and maintain BridgeCmdr.
- [electron-builder)](https://www.electron.build/).
- [VisualStudio Code](https://code.visualstudio.com/)

For a complete list of tools, see the `package.json` file. Any other dependencies not listed above
or in the package file are dependencies of those packages.
For a complete list of tools, see the `package.json` file. Any other dependencies not listed above or in the package
file are dependencies of those packages.

### Recommended IDE Setup

Expand All @@ -103,7 +102,8 @@ or in the package file are dependencies of those packages.

#### Type Support for `.vue` Imports in TS

TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking.
TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for
type checking.

### Development

Expand All @@ -116,59 +116,30 @@ based operating system is required. The following steps will get you setup on a
requests back to the official source code. Also start personal branches from `develop`.
- Download the [source](https://github.com/6XGate/bridgecmdr/archive/develop.zip) and extract it.
3. Open a terminal clone and go to the folder into which source was cloned or extracted.
4. Install the node packages; `npm ci`
4. Install the node packages; `yarn`
5. Build and run the app;

- For hot-reload mode: `npm run dev`
- For product build preview: `npm run preview`
- For hot-reload development mode: `yarn dev`
- For product builds: `yarn build`
- For packaged application: `yarn package`

### Docker and ARM support

If you want to run this in an ARM version of Linux, and don't have an ARM system or want to run on
one. You can set up your system to support running ARM Docker container via QEMU's static user
binary format translation. See
[this article on Docker.com](https://www.docker.com/blog/getting-started-with-docker-for-arm-on-linux/)
for more information. Some Linux distribution have packages or instruction for their own
packaged version of QEMU and the binary translation support.

The docker container can be built and activated in one command in this repository with
`npm run docker:sh`. You may need to run `npm ci` to reinstall all packages with the
proper ARM bindings. Using this container is really only useful when packaging the
application with `npm run dist`.

### Packaging the Installer

To package or build the install, you will need to follow the above steps you acquire the a working copy of the source
code on a Raspberry Pi running Raspbian, the only supported operating system.

There are two ways to build the installer package depending on which model of Raspberry Pi you have.
You can run ARM Docker containers on IA32 or AMD64 to package the application using the following means:

#### Using a 1GiB Raspberry Pi and a desktop computer.
- Docker Desktop with multi-platform support enabled.
- On Linux, using [qemu static binary format support](https://www.docker.com/blog/getting-started-with-docker-for-arm-on-linux/).

The following systems must use this method:
You can start a container for building purposes by calling `docker compose run --build -it --rm build`. After doing so
you will need to run `yarn` to reinstall the native code dependencies with their proper native bindings.

- Raspberry Pi 3 Model B
- Raspberry Pi 3 Model B+
- 1GiB Raspberry Pi 4 Model B,
- Any model with lesser specs than those above, though this is as untested as running BridgeCmdr on it.

Though not optimal, the only way to build a package on a 1GiB Raspberry Pi is to use a desktop computer running a
GNU/Linux based operating system to build the user interface and the Pi to build the installer package.

1. On both systems, install the node packages; `npm ci`
2. On the desktop system, build the user interface source; `npm run build`
3. Copy the `dist` folder from the desktop system to project folder on the Raspberry Pi system.
4. Package the installer on the Raspberry Pi system; `npm run dist`

#### Using Raspberry Pi with more RAM.

If you are running a Raspberry Pi 4 with 2GiB or 4GiB, all instructions can be done without copying the user interface
files and you will only use that single system. This is a simplest process.
### Packaging the Installer

1. Install the node packages; `npm ci`
2. Build the installer package; `npm run dist`
To package the application, you will need to use `yarn package` steps you acquire the working copy of the source code
on an ARM system or in an ARM Docker container. It is not recommended to build directly on the Raspberry Pi since
the systems can be underpowered for such a purpose.

#### The Package

You should now have a package ending in `.AppImage` in the `dist` folder.
This package can be run like any other AppImage file.
You should now have a package ending in `.AppImage` in the `dist` folder. This package can be run like any other
AppImage file.

0 comments on commit 96c9864

Please sign in to comment.