From 945ba0938c5be32c1fedf175c655ab7157271175 Mon Sep 17 00:00:00 2001
From: EricClaeys <83164203+EricClaeys@users.noreply.github.com>
Date: Wed, 9 Mar 2022 01:21:35 -0600
Subject: [PATCH] README.md: Misc updates
* Many changes to add clarification.
* Added "Click here" buttons which display text. This significantly shortens the default view of the file, increasing the chance that people will actually read it.
* Removed unused, hidden text.
* Added hidden text for version 0.8.3.3 changes (will unhide when that version is ready).
---
README.md | 258 ++++++++++++++++++++++++++++++++++++++----------------
1 file changed, 182 insertions(+), 76 deletions(-)
diff --git a/README.md b/README.md
index 58864f0dd..07b986fad 100644
--- a/README.md
+++ b/README.md
@@ -4,16 +4,22 @@
This is the source code for the Allsky Camera project described [on Instructables](http://www.instructables.com/id/Wireless-All-Sky-Camera/).
+
+
## Required Action Needed
When upgrading from a release _prior to_ 0.8.3 you **MUST** follow the steps [here](https://github.com/thomasjacquin/allsky/wiki/Upgrade-from-0.8.2-or-prior-versions).
-
+
+
+
## Requirements
+Click here
+
In order to get the camera working properly you will need the following hardware:
* A camera (Raspberry Pi HQ or ZWO ASI)
@@ -22,50 +28,49 @@ In order to get the camera working properly you will need the following hardware
**NOTE:** Owners of USB2.0 cameras such as ASI120MC and ASI120MM may need to do a [firmware upgrade](https://astronomy-imaging-camera.com/software-drivers). This changes the camera to use 512 byte packets instead of 1024 which makes it more compatible with most hardware.
**NOTE:** The T7 / T7C cameras, e.g., from Datyson or other sellers, are not officially supported but persistent users may get them to work by following [these instructions](https://github.com/thomasjacquin/allsky/wiki/Troubleshoot:-T7-Cameras).
+Click here
+
PatriotAstro created a [video](https://www.youtube.com/watch?v=j9xHsST2EeY) describing the installation steps below. Feel free to check it out.
-Another [video](https://www.youtube.com/watch?v=y6EFfLo4XxE) covers the installation on a Raspberry Pi zero with both ZWO and RPiHQ cameras.
+Another [video](https://www.youtube.com/watch?v=y6EFfLo4XxE) covers the installation on a Raspberry Pi Zero with both ZWO and RPiHQ cameras.
You will need to install the Raspbian Operating System on your Raspberry Pi. Follow [this link](https://www.raspberrypi.org/documentation/installation/installing-images/) for information on how to do it.
-Make sure you have a working internet connection by setting it through [the terminal](https://www.raspberrypi.org/documentation/configuration/wireless/wireless-cli.md).
+Make sure you have a working Internet connection by setting it through [the terminal window](https://www.raspberrypi.org/documentation/configuration/wireless/wireless-cli.md).
-1. Start by installing git if not already there. Open the terminal and type the following:
+1. Start by installing git if not already there. Open the terminal window (or SSH into your Pi) and type the following:
```shell
sudo apt-get install git
```
2. Now fetch the code from this GitHub page:
```shell
+ cd
git clone --recursive https://github.com/thomasjacquin/allsky.git
```
-3. Then navigate to the allsky directory:
+3. Then navigate to the new allsky directory and run the installation script:
```shell
cd allsky
- ```
-
-4. Now, run the install script:
- ```shell
./install.sh # PatriotAstro's video shows using "sudo"; that is no longer needed
```
-**NOTE:** Version 0.8 added many new settings and changed the name of several existing settings. For example, there are now separate brightness levels for daytime and nighttime, called "daybrightness" and "nightbrightness". Version 0.7 only had "brightness" that applied to both day and nighttime. It's very important that you save a copy of your current settings prior to upgrading to version 0.8 so you can restore them properly.
-The WebUI from the `allsky-portal` package uses these new settings so it's also important to update AllSky **prior to** updating the WebUI.
-
-Also note that in version 0.8.3 the default image file created and uploaded is called "image.jpg". The prior "image-resize.jpg" and "liveview-image.jpg" are no longer created. Keep that in mind if you copy the image to a remote web server - it will need to know about the new name.
-
-Some users have reported ASI_ERROR_TIMEOUT errors with their ZWO cameras in verion 0.8. Click [here](https://github.com/thomasjacquin/allsky/wiki/Troubleshoot:-ASI_ERROR_TIMEOUTs) to troubleshoot.
+Some users have reported ASI_ERROR_TIMEOUT errors with their ZWO cameras. Click [here](https://github.com/thomasjacquin/allsky/wiki/Troubleshoot:-ASI_ERROR_TIMEOUTs) to troubleshoot.
-## Configuration
-
-There are many configuration variables that need to be set as well as many optional ones. Please see the [allsky Settings](https://github.com/thomasjacquin/allsky/wiki/allsky-Settings) page for a list of them.
+There are many configuration variables that need to be set. Please see the [allsky Settings](https://github.com/thomasjacquin/allsky/wiki/allsky-Settings) page for a list of them.
+Click here
### Autostart
@@ -83,48 +88,73 @@ sudo systemctl stop allsky
sudo systemctl restart allsky
sudo systemctl status allsky
```
+> Tip: Add lines like the following to `~/.bashrc` to save typing:
+```shell
+alias start='sudo systemctl start allsky'
+```
+You will then only need to type `start` to start the software.
### Manual Start
Starting the program from the terminal can be a great way to track down issues as it provides debug information.
-To start the program manually, make sure the service is stopped (see above), then run:
+To start the program manually, run:
```
-cd allsky
+sudo systemctl stop allsky
+cd ~/allsky
./allsky.sh
```
-If you are using a desktop environment (Pixel, Mate, LXDE, etc) or using remote desktop or VNC, you can add the `preview` argument in order to show the images the program is currently saving.
+If you are using a desktop environment (Pixel, Mate, LXDE, etc) or using remote desktop or VNC, you can add the `preview` argument to show the images the program is currently saving in a separate window.
```
./allsky.sh preview
```
+Click here
+
See this [Wiki page](https://github.com/thomasjacquin/allsky/wiki/How-to-update-the-software) for instructions on how to update the AllSky software.
+**NOTE:** Version 0.8 added many new settings and changed the name of several existing settings. For example, there are now separate brightness levels for daytime and nighttime, called "daybrightness" and "nightbrightness". Version 0.7 only had "brightness" that applied to both day and nighttime. It's very important that you save a copy of your current settings prior to upgrading to version 0.8 so you can restore them properly.
+The WebUI from the `allsky-portal` package uses these new settings so it's also important to update AllSky **prior to** updating the WebUI.
+
+Also note that in version 0.8.3 the default image file created and uploaded is called **image.jpg**. The prior "image-resize.jpg" and "liveview-image.jpg" are no longer created. Keep that in mind if you copy the image to a remote web server - it will need to know about the new name.
+Click here
+
If you don't want to configure the camera using the terminal, you can install the [WebUI](https://github.com/thomasjacquin/allsky-portal).
-Please note that this will change your hostname to **allsky** (or whatever you called it when installing), install the lighttpd web server, and replace your `/var/www/html` directory. It will also move `config/settings_*.json` to `/etc/raspap/settings_*.json`.
-Using the WebUI is **highly** recommended as it provides additional information on each setting and allows error checking behind the scenes.
+Note that this will:
+* change your hostname to **allsky** (or whatever you called it when installing)
+* install the lighttpd web server
+* replace your `/var/www/html` directory
+* move the `allsky/config/settings_*.json` configuration files to `/etc/raspap`
+
+Using the WebUI is **highly** recommended as it provides additional information on each setting and allows error checking behind the scenes. The Wiki and other documentation assume you have WebUI installed. To install it:
```shell
sudo gui/install.sh
```
-It will prompt you for a new name of your Pi (default is 'allsky').
After you complete the WebUI setup, you'll be able to administer the camera using the WebUI by navigating to
-```sh
-http://your_raspberry_IP_address
```
-or
-```sh
+http://your_raspberry_IP_address
+ OR
http://allsky.local
```
-Note: If you changed the name of your Pi (to 'piname', for example, instead of the default 'allsky') during the WebUI install then use this:
-```sh
+Note: If you changed the name of your Pi (to 'piname', for example) during the WebUI installation then use this:
+```
http://piname.local
```
@@ -132,59 +162,99 @@ The default username is **admin** and the default password is **secret**. If th
A public page is also available in order to view the current image without having to log into the portal and without being able to do any administrative tasks. This can be useful for people who don't have a personal website but still want to share a view of their sky:
-```sh
+```
http://your_raspberry_IP/public.php
```
Make sure this page is publically viewable.
If it is behind a firewall consult the documentation for your network equipment for information on allowing inbound connections.
-
+Click here
+
The dark frame subtraction feature removes hot pixels from night sky images. The concept is the following: Take an image with a cover on your camera lens and let the software subtract that image later from all images taken throughout the night.
See [this Wiki page](https://github.com/thomasjacquin/allsky/wiki/Dark-Frames-Explained) on dark frames for instructions on how to use them.
+Click here
+
By default, a timelapse video is generated at the end of nighttime from all of the images captured in the last 24 hours.
-To disable timelapse, open `config/config.sh` and set
+To disable timelapse, open `allsky/config/config.sh` and set
-```
+```shell
TIMELAPSE="false"
```
-Example to generate a timelapse manually:
+To generate a timelapse video manually:
-```
-./scripts/generateForDay.sh -t 20210710
+```shell
+cd ~/allsky
+scripts/generateForDay.sh -t 20220710
```
-**Note:** If you are unable to create a timelapse, see [this Wiki page](https://github.com/thomasjacquin/allsky/wiki/Troubleshooting:-timelapse) on troubshooting timelapse issues.
+**Note:** If you are unable to create a timelapse, see [this Wiki page](https://github.com/thomasjacquin/allsky/wiki/Troubleshooting:-timelapse).
+Click here
+
-A **Keogram** is an image giving a quick view of the night activity. It was originally invented to study the aurora borealis.
-For each nighttime image a central vertical column 1 pixel wide is extracted. All these columns are then stitched together from left to right. This results in a timeline that reads from dusk to dawn.
+A **Keogram** is an image giving a quick view of the day's activity. It was originally invented to study the aurora borealis.
+For each image a central vertical column 1 pixel wide is extracted. All these columns are then stitched together from left to right. This results in a timeline that reads from dawn to the end of nighttime (the image above only shows nighttime data since daytime images were turned off).
See the [Keogram Wiki page](https://github.com/thomasjacquin/allsky/wiki/Keograms-explained) for more details.
+
+To generate a keogram image manually:
+```shell
+cd ~/allsky
+scripts/generateForDay.sh -k 20220710
+```
+Click here
+
**Startrails** are generated by stacking all the images from a night on top of each other.
See the [Startrails Wiki page](https://github.com/thomasjacquin/allsky/wiki/Startrails-Explained) for more details.
+
+To generate a startrails image manually:
+```shell
+cd ~/allsky
+scripts/generateForDay.sh -s 20220710
+```
+Click here
+
You can specify how many days worth of images to keep in order to keep the Raspberry Pi SD card from filling up. Automatic deletion is enabled by default and will keep 2 weeks of data on the card.
```
AUTO_DELETE="true"
@@ -193,32 +263,47 @@ NIGHTS_TO_KEEP=14
Set to "false" to keep all nights (requires manual management of SD card free space).
**NOTE:** "NIGHTS_TO_KEEP" should really be "DAYS_TO_KEEP" since it will keep that many 24-hour days of data, not just the nighttime data.
+Click here
-When using the allsky service, issues are written to a log file. In case the program stopped, crashed, or behaved in an abnormal way, take a look at:
+
+When using Allsky, information is written to a log file. In case the program stopped, crashed, or behaved in an abnormal way, take a look at:
```
tail /var/log/allsky.log
```
+
+There are other temporary log files in `allsky/tmp` that are used for debugging.
+Click here
+
+
You can display your files on a website, either on the Pi itself or on another machine.
### On the Pi
If you want to host the website on your Raspberry Pi, run the following command. Note that this requires first installing the WebUI.
-```
+```shell
+cd ~/allsky
website/install.sh
```
-And set these variabled in `ftp-settings.sh`:
-```
+And set these variables in `allsky/config/ftp-settings.sh`:
+```shell
PROTOCOL='local'
IMAGE_DIR='/var/www/html/allsky/'
-VIDEOS_DIR=`/var/www/html/allsky/videos`
-KEOGRAM_DIR=`/var/www/html/allsky/keograms`
-STARTRAILS_DIR=`/var/www/html/allsky/startrails`
+VIDEOS_DIR='/var/www/html/allsky/videos'
+KEOGRAM_DIR='/var/www/html/allsky/keograms'
+STARTRAILS_DIR='/var/www/html/allsky/startrails'
```
### On a different machine
@@ -226,33 +311,38 @@ If you want to host the website on a _different_ machine, like in this [example]
### Website settings
Once you've installed the website, either on your Pi or another machine, look at the descriptions of the settings on the [allsky-website Settings page](https://github.com/thomasjacquin/allsky/wiki/allsky-website-Settings).
+Click here
+
+
Experienced users may want to add some additional processing steps at the end of nighttime.
-To do so, copy `scripts/endOfNight_additionalSteps.repo` to
-`scripts/endOfNight_additionalSteps.sh` and then add your additional processing steps which
+To do so:
+```shell
+cd ~/allsky/scripts
+mv endOfNight_additionalSteps.repo scripts/endOfNight_additionalSteps.sh
+```
+and then add your additional processing steps which
will be run after the usual end-of-night processing, but before the deletion of any old image files.
-Edit this file via the "Editor" link on the left side of the WebUI page.
-
-
+
+
## Share your sky
If you've built an allsky camera, please send me a message and I'll add you to the [map](http://www.thomasjacquin.com/allsky-map).
+
+
## Release notes
-* version **0.7**: Added Raspberry Pi camera HQ support (Based on Rob Musquetier's fork)
+* version **0.7**:
+ * Added Raspberry Pi camera HQ support (Based on Rob Musquetier's fork)
* Support for x86 architecture (Ubuntu, etc)
* Temperature dependant dark frame library
* Browser based script editor
* Configuration variables to crop black area around image
* Timelapse frame rate setting
* Changed font size default value
-* version **0.8**: Workaround for ZWO daytime autoexposure bug.
- * Improved exposure transitions between day and night so there's not a huge change in brightness.
+-->
+* version **0.8**:
+ * Workaround for ZWO daytime autoexposure bug.
+ * Improved exposure transitions between day and night so there's not such a huge change in brightness.
* Decrease in ZWO sensor temperature.
* Lots of new settings, including splitting some settings into day and night versions.
* Error checking and associated log messages added in many places to aid in debugging.
* Ability to have "notification" images displayed, such as "Allsky is starting up" and "Taking dark frames".
- * Ability to resize uploaded images to a user-specified size.
+ * Ability to resize uploaded images.
* Ability to set thumbnail size.
* Ability to delete bad images (corrupt and too light/dark).
* Ability to set an image file name prefix.
* Ability to reset USB bus if ZWO camera isn't found (requires "uhubctl" command to be installed).
- * Ability to specify format of time displayed on image and temperature displayed in Celcius, Fahrenheit, or both.
+ * Ability to specify the format of the time displayed on images.
+ * Ability to have the temperature displayed in Celcius, Fahrenheit, or both.
* Ability to set bitrate on timelapse video.
-* version **0.8.1**: Rearranged directory structure.
+* version **0.8.1**:
+ * Rearranged the directory structure.
* Created a Wiki with additional documentation and troubleshooting tips.
* Renamed several variables in `config.sh` and `ftp-settings.sh`.
* CAMERA type of "auto" is no longer supported - you must specify "ZWO" or "RPiHQ".
@@ -300,10 +394,11 @@ If you've built an allsky camera, please send me a message and I'll add you to t
* The WebUI will now show the Pi's throttle and low-voltage states, which is useful for debugging.
* Darks work better.
* Many bug fixes, error checks, and warnings added.
-* version **0.8.3**: Works on Bullseye operating system.
+* version **0.8.3**:
+ * Works on Bullseye operating system.
* RPiHQ version:
- * Has an improved auto-exposure algorithm. To use it, set `CAPTURE_EXTRA_PARAMETERS="-daymean 0.3 -nightmean 0.3"` in config.sh (a future version will allow this to be set via the WebUI).
- * Has many new settings including support for most of the text overlay features that are supported by the ZWO version. The "extra text" feature will be supported in a future version).
+ * Has an improved auto-exposure algorithm. To use it, set `CAPTURE_EXTRA_PARAMETERS="-daymean 0.5 -nightmean 0.2"` in config.sh (a future version will allow this to be set via the WebUI).
+ * Has many new settings including support for most of the text overlay features that are supported by the ZWO version. The "extra text" feature will be supported in a future version.
* New and changed config.sh variables, see the [Software Settings](https://github.com/thomasjacquin/allsky/wiki/allsky-Settings) Wiki page for more information:
* `IMG_UPLOAD_FREQUENCY`: how often the image should be uploaded to a website. Useful with slow uplinks or metered Internet connections.
* `IMG_CREATE_THUMBNAILS`: specifies whether or not thumbnails should be created for each image.
@@ -313,9 +408,20 @@ If you've built an allsky camera, please send me a message and I'll add you to t
* Replaced `saveImageDay.sh` and `saveImageNight.sh` with `saveImage.sh` that has improved functionality, including passing the sensor temperature to the dark subtraction commands, thereby eliminating the need for the "temperature.txt" file.
* The image used by the websites (default: image.jpg) as well as all temporary files are now written to `allsky/tmp`. **NOTE**: if you are using the Allsky Website you will need to change the "imageName" variable in `/var/www/html/allsky/config.js` to `"/current/tmp/image.jpg"`.
* You can **significanly** reduce wear on your SD card by making `allsky/tmp` a [memory-based filesystem](https://github.com/thomasjacquin/allsky/wiki/Miscellaneous-Tips).
+
-## Donation
+
+## Donation
If you found this project useful, here's a link to send me a cup of coffee :)
[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=MEBU2KN75G2NG&source=url)