From 96c9864f3760b8a0568145d8bbfade018ab4bc76 Mon Sep 17 00:00:00 2001 From: Matthew Holder Date: Fri, 30 Aug 2024 22:56:02 -0500 Subject: [PATCH] Updated the README file. --- README.md | 125 +++++++++++++++++++++--------------------------------- 1 file changed, 48 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index 98c241c..aa4bf2f 100644 --- a/README.md +++ b/README.md @@ -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 . @@ -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 @@ -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 @@ -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 @@ -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.