TheBeard Science Project Wiki - User contributions [en]

Chrome/Chromium Browser

2021-04-07T04:15:26Z

Beard: /* Disable Hardware Media Key Handling */

== Hidden Settings ==

Type <code>chrome://about</code> into you address bar at the top to get a list of all internal pages in Chrome or Chromium browsers. These pages give you a lot of additional configurations, developer options, and information. Many of the hidden configurations can break things, so be careful!

The major one is <code>chrome://flags</code> which has a lot of advanced configuration tweaks.

For similar hidden configurations in other browsers, read this article: http://www.howtogeek.com/139736/how-to-change-hidden-advanced-settings-in-any-browser/

== Disable Hardware Media Key Handling ==

With this feature, media that is playing in Chrome will make media controls available to the Operating System, and in Windows 10 this means there will be a media control box that display on the desktop and even on the lock screen.

To disable it, go to this link, set it to disabled, and reload Chrome:
[[chrome://flags/#hardware-media-key-handling]]

Unfortunately, this also disables the nice feature of being able to use any media controls you have on your keyboard.

== Disable "Use passwords saved in your Google Account" ==

Load chrome://flags in the browser’s address bar.
# Search for “account data storage”.
# Set the flag “Enable the account data storage for passwords” to Disabled.
# Set the flag “Enable IPH for the account data storage for passwords” to Disabled.
# Restart Google Chrome.

Automatic Email and Text Notifications

2021-02-26T14:15:30Z

Beard: /* Email and Text Messaging with SSMTP */

These tutorials describe my method of automatic messaging via email and text (SMS) from my Linux servers.

== Required Packages ==

These packages are necessary for the all the following sections of this tutorial. In Debain, install them with <code>apt-get</code>:
<source lang="sh">
apt-get install ssmtp procmail fetchmail
</source>

== Directory Structure ==

Just for reference, here are the locations of the relevant files:
<source>
/
├── etc
│ └── ssmtp
│ └── ssmtp.conf
└── scripts
├── config
│ ├── accounts.conf
│ ├── ddns-fetchmailrc
│ └── ddns-mailprocess.sh
├── ddns.sh
├── email.sh
├── external-ip.sh
├── notifications.sh
└── sms.sh
</source>

And permissions:
<source lang="shell">
ls -l /scripts
</source>
<pre class="out">
drwxr-xr-x 4 root config 4096 Jun 20 08:52 config
-rwxr-xr-- 1 root root 260 Jun 20 08:40 ddns.sh
-rwxr-xr-- 1 root mailers 564 Apr 23 12:18 email.sh
-rwxr-xr-- 1 root root 529 Apr 27 07:56 external-ip.sh
-rwxr-xr-- 1 root root 3834 May 15 08:32 notifications.sh
-rwxr-xr-- 1 root texters 545 Apr 23 12:24 sms.sh
</pre>

<source lang="shell">
ls -l /scripts/config
</source>
<pre class="out">
-rwxr-x--- 1 root mailers 147 May 1 13:01 accounts.conf
-rwx------ 1 root root 246 May 21 09:49 ddns-fetchmailrc
-rwxr-x--- 1 root config 604 Jun 20 08:52 ddns-mailprocess.sh
</pre>

== Create Security Groups ==

I use group membership to control read access to certain files. You don't have to do this, but it was useful for me.

Create the groups:
<source lang="sh">
groupadd texters #allowed to sent text messages
groupadd mailers #allowed to send email messages
groupadd config #allowed to read other config files
</source>

You can add a user to all three groups like this:
<source lang="sh">
usermod -aG texters,mailers,config username
</source>

== Email and Text Messaging with SSMTP ==

First set up the <code>/etc/ssmtp/ssmtp.conf</code>. I use a dedicated Gmail account (named serveraccount@gmail.com in the example below) for all of my server messaging. When I receive an email from my server, it will look like it's coming from that Gmail.

Make a backup copy of the original config:
<source lang="sh">
cp /etc/ssmtp/ssmtp.conf /etc/ssmtp/ssmtp.conf.orig
</source>

Here are the contents of my modified <code>/etc/ssmtp/ssmtp.conf</code>. Replace the relevant values.
<source lang="sh">
#
# Config file for sSMTP sendmail
#
# The person who gets all mail for userids < 1000
# Make this empty to disable rewriting.
root=serveraccount

# The place where the mail goes. The actual machine name is required no
# MX records are consulted. Commonly mailhosts are named mail.domain.com
#mailhub=mail

# Where will the mail seem to come from?
rewriteDomain=gmail.com

# The full hostname
# This can be left as 'localhost'
hostname=localhost

# Are users allowed to set their own From: address?
# YES - Allow the user to specify their own From: address
# NO - Use the system generated From: address
FromLineOverride=YES

mailhub=smtp.gmail.com:587
UseStartTLS=YES
UseTLS=YES
AuthMethod=LOGIN
AuthUser=serveraccount@gmail.com
AuthPass=InsertPasswordHere
TLS_CA_File=/etc/pki/tls/certs/ca-bundle.crt
FromLineOverride=YES
</source>

Since the file contains a password, make sure the file is not readable to normal users.
<source lang="sh">
chown root:mail /etc/ssmtp/ssmtp.conf
chmod 640 /etc/ssmtp/ssmtp.conf
</source>

And because you don't have to remember this password, it would be a good idea to make it very long and complex (16+ characters; uppercase, lowercase, numbers, and special characters; no dictionary words).

You now need to log onto the serveraccount Gmail account and enable "less secure apps" at https://myaccount.google.com/lesssecureapps?pli=1 
[[File:Gmail-less-secure-app.png|frameless|600px]]

Here is more info about less secure apps: https://support.google.com/cloudidentity/answer/6260879?hl=en

You should now be able use the <code>ssmtp</code> command line tool from your server. Most of the time, you will need to include a subject line. It's important that it follows the format below (capital 'S' on Subject, colon, space, YourSubject, two newlines):
<source lang="sh">
echo -e "Subject: Hi\n\nHello, world!" | ssmtp myaccount@yahoo.com
</source>

== Create a Secure Accounts File ==

For some of the automatic messaging, you need to store text and email accounts in a file. To figure out the destination address to send text (SMS) messages to your cell, look on your cell provider's website for the proper account/domain name. It will probably be something like "<your-phone-number>@<provider-domain>". [https://kb.sandisk.com/app/answers/detail/a_id/17056/~/list-of-mobile-carrier-gateway-addresses List of provider addresses]

Contents of my <code>/scripts/config/accounts.conf</code> file:
<source lang="sh">
#!/bin/bash
#
# Secure account information
# Permissions must be 750 root:mailers

smsto="17775551234@myprovider.net"
mailto="myaccount@yahoo.com"
</source>

Change the permissions on the file:
<source lang="sh">
chown root:mailers /scripts/config/accounts.conf
chmod 750 /scripts/config/accounts.conf
</source>

== Email Script ==

This script can be used to send an email message.

Contents of the file <code>/scripts/email.sh</code>:
<source lang="shell">
#!/bin/bash

# Send email message:
# Usage: $0 "<Subject>" "<Message>"

default_subject="Alert from Server (`date`)"

subject=""
message=""

case $# in
2)
subject="$1"
message="$2"
;;
1)
subject="$default_subject"
message="$1"
;;
*)
echo "Send Email Message:"
echo " Usage: `basename $0` \"Message\""
echo " `basename $0` \"Subject\" \"Message\""
exit 1
;;
esac

dir="$(cd $(dirname ${BASH_SOURCE[0]})&&pwd)"
. $dir/config/accounts.conf

echo -e "Subject: $subject\n\n$message" | /usr/sbin/ssmtp $mailto
</source>

Set up permissions:
<source lang="sh">
chown root:mailers /scripts/email.sh
chmod 754 /scripts/email.sh
</source>

You can create an alias so you can quickly run this from the command line:
<source lang="sh">
echo "alias email='/scripts/email.sh'" >>~/.bashrc
source ~/.bashrc
</source>

Usage:
<source lang="sh">
# Send message with default subject
email "This is a test message."

# Send message with a subject
email "Test Subject" "This is a test message."
</source>

== Text Script ==

This script can be used to send a text (SMS) message.

Contents of the file <code>/scripts/sms.sh</code>:
<source lang="shell">
#!/bin/bash

# Send SMS message:
# Usage: $0 "<Subject>" "<Message>"

default_subject="Alert"

subject=""
message=""

case $# in
2)
subject="$1"
message="$2"
;;
1)
subject="$default_subject"
message="$1"
;;
*)
echo "Send SMS Message:"
echo " Usage: `basename $0` \"Message\""
echo " `basename $0` \"Subject\" \"Message\""
exit 1
;;
esac

dir="$(cd $(dirname ${BASH_SOURCE[0]})&&pwd)"
. $dir/config/accounts.conf

echo -e "To: $smsto\nSubject: $subject\n\n$message" | /usr/sbin/ssmtp $smsto
</source>

Set up permissions:
<source lang="sh">
chown root:texters /scripts/sms.sh
chmod 754 /scripts/sms.sh
</source>

You can create an alias so you can quickly run this from the command line:
<source lang="sh">
echo "alias sms='/scripts/sms.sh'" >>~/.bashrc
source ~/.bashrc
</source>

Usage:
<source lang="sh">
# Send message with default subject
sms "This is a test message."

# Send message with a subject
sms "Test Subject" "This is a test message."
</source>

== Scheduled Notifications Script ==

One of my life improvement tasks was to organize chores into scheduled chore days and rely on text/email notification to remind me to do them.

This dramatically reduced the amount of time I spend working on chores, and the amount of effort I spend thinking about what needs to be done. I could barely get projects done because every day I was loading my task list with chores. Now I don't think about chores until I'm notified. When I think of new chores, new items for my inventory, or other things I need to be reminded of, I update my checklists. When I feel I can improve scheduling or consolidate chores, I update my notifications script.

This utilizes the Email Script and Text Script from the previous sections.

Contents of the file <code>/scripts/notifications.sh</code>:
<source lang="shell">
#!/bin/bash
#
# Send regular notifications.
# Currently set to run daily at NOON.
#

# Get current datetime values
dt=(`date +%Y\ %m\ %d\ %H\ %M\ %S\ %a\ %s\ %I\ %p\ %Z`)
y=$((10#${dt[0]})) #year
M=$((10#${dt[1]})) #month
d=$((10#${dt[2]})) #day
h=$((10#${dt[3]})) #hour(24)
m=$((10#${dt[4]})) #minute
s=$((10#${dt[5]})) #second
w=${dt[6]} #day of week (eg. Sun)
e=$((10#${dt[7]})) #epoch
t=$((10#${dt[8]})) #hour(12)
p=${dt[9]} #meridian (AM/PM)
z=${dt[10]} #timezone (eg. PDT)

# Schedule command when date ($1) matched regex ($2) with extra grep parameters ($3)
# Use parameter -P at $3 for perl regex: in case you need to use (str1|str2).
# Example: schedule $M$d "(115|21)" -P && sms "Subject" "Message"
# Don't use -P when you want a range of numbers including 2 or more digit numbers (ie. [1-15]).
schedule(){ echo "$1" | grep -wq $3 "$2";}
sms(){ /scripts/sms.sh "$1" "$2";}
eml(){ /scripts/email.sh "$1" "$2";}
notify(){ sms "$1" "$2";eml "$1" "$2";}

# =================================
# ==== Temporary Notifications ====
# =================================

# Dentist appointment
#schedule $M$d "58" && notify "Dentist" "Appointment 4:00pm 10/31/2017"

# =================================
# ====== Chore Notifications ======
# =================================

# LAUNDRY DAY
# Day before
schedule $w$d "Mon[1-7]" && notify "LAUNDRY DAY" "WORK: Check gas. HOME: Do laundry, put laundry away."
schedule $w$d "Mon(15|16|17|18|19|20|21)" -P && notify "LAUNDRY DAY" "WORK: Check gas. HOME: Do laundry, put laundry away."

# WEEKLY CLEANING DAY
schedule $w "Tue" && notify "WEEKLY CLEANING DAY" "WORK: Fill gas, shopping. HOME: Clean, litter, sweep/vac, fridge, trash, check meds."
# Day after
schedule $w "Wed" && notify "WEEKLY REMINDER" "Order meds if necessary."

# MONTHLY CLEANING DAY
schedule $w$d "Tue[1-7]" && notify "MONTHLY CLEANING DAY" "WORK: Car stuff. HOME: Dishes, kitchen, bathroom, dust, inventory."

# BUSINESS DAY
schedule $d "[1-4]" && notify "BUSINESS DAY" "Rent due before 5th (\$720). Fedloan, budgeting, donations, next-buy."

# TECH DAY
schedule $w$d "Mon[1-7]" && notify "TECH DAY" "WORK: Updates, phone, healthcheck, security scan, organize files. HOME: Organize Workstation/Laptop, USB drives."

# SHOPPING DAY
schedule $w$d "Wed[1-7]" && notify "SHOPPING DAY" "Shopping, carwash. Maybe do during lunch."

# GROOMING DAY
schedule $w$d "Sun[1-7]" && notify "GROOMING DAY" "Shave/trim, clip nails."
schedule $w$d "Sun(15|16|17|18|19|20|21)" -P && notify "GROOMING DAY" "Shave/trim, clip nails."

# ELIMINATION DAY
schedule $w$d "Sun(15|16|17|18|19|20|21)" -P && notify "ELIMINATION DAY" "Do at least one item on TO_ELIMINATE list."

# INVENTORY DAY
# Disabled. Inventory is now included in monthly cleaning day.
# schedule $w$d "Tue[1-7]" && notify "INVENTORY DAY" "Do home, car, and office inventory."

# =================================
# = Other Permanent Notifications =
# =================================

# Air filter replacement notifications
schedule $M$d "71" && notify "Air Filter" "Holmes HAP726: Replace HEPA filters (model:HAPF600,qty:2)"
schedule $M$d "[1|7]1" && notify "Air Filter" "Holmes HAP726: Replace Carbon filters (model:HAPF600,qty:2)"
</source>

Now set the permissions:
<source lang="sh">
chown root:root /scripts/external-ip.sh
chmod 754 /scripts/external-ip.sh
</source>

== Reporting External IP Address ==

My home server does not have a static IP address, so I use dynamic DNS. With my free DDNS service, I have to renew the domain name every 30 days. So if I forget to renew it, it will expire and I won't be able to access my server unless I know the IP address. As a contingency, I created a script that sends my external IP address to an email account every 6 hours. Then at least I would be able find out what my last IP was and use that to access my server.

Contents of the file <code>/scripts/external-ip.sh</code>:
<source lang="shell">
#!/bin/bash

log="/var/log/external-ip.log"
ipsrc="http://checkip.dyndns.org"
date="`date`"
addr="myaccount@yahoo.com"

ip=`curl -s --connect-timeout 3 $ipsrc 2>/dev/null|grep -Po "Current IP Address: .*?\<"|tr '<' '\0'`
echo "IP: $ip"

if [ -z "$ip" ];then
echo "$date ERROR: Could not get external IP from $ipsrc" >>$log
else
echo -e "Subject:[`hostname`] $date $ip" | /usr/sbin/ssmtp $addr
if [ "$?" = "0" ];then
echo "$date SUCCESS: $ip sent to $addr" >>$log
else
echo "$date ERROR: Could not send to $addr" >>$log
fi
fi
</source>

Now set the permissions:
<source lang="sh">
chown root:root /scripts/external-ip.sh
chmod 754 /scripts/external-ip.sh
</source>

This script appends to a log file <code>/var/log/external-ip.log</code>:
<source lang="sh">
touch /var/log/external-ip.log
chown root:root /var/log/external-ip.log
chmod 644 /var/log/external-ip.log
</source>

== Automatic Email Download ==

As mentioned in a previous section, I use free dynamic DNS which requires that I renew it manually every 30 days. I need to remind myself to do this. My provider sends an email notification a few days before it expires, but I hate email and I don't want it in my face all the time, certainly not in my phone.

The best solution I found was to retrieve the email automatically and send me a text message with only the subject line in the message. I eventually created a second method of notification: it generates a file in a place that I regularly go, the folder that contains all of my to-do lists.

Contents of the file <code>/scripts/ddns.sh</code>:
<source lang="shell">
#!/bin/bash
#
# This script is run by a cron job.

/usr/bin/fetchmail -N -d0 -f "/scripts/config/ddns-fetchmailrc" -m "/scripts/config/ddns-mailprocess.sh"

alertfile="/shares/Private/000__DDNS-ALERT__.txt"
if [ -e $alertfile ];then
chown root:root $alertfile
chmod 777 $alertfile
fi
</source>

Contents of the file <code>/scripts/config/ddns-mailprocess.sh</code>:
<source lang="shell">
#!/bin/bash
#
# This script is run by /scripts/ddns.sh

mailto="17775551234@myprovider.net"
date="`date`"
log="/var/log/ddns.log"
alertfile="/shares/Private/000__DDNS-ALERT__.txt"
sms="/scripts/sms.sh"

cat /dev/stdin | grep -i "^Subject:" | sed 's/Subject\://g' | $sms "DDNS" "`cat /dev/stdin` ( $date )" &&\
echo "$date - DDNS notification sent to $mailto" | tee -a $log | sed "s/$mailto/cell\ phone/g" >$alertfile &&\
chmod 777 $alertfile
</source>

Contents of the file <code>/scripts/config/ddns-fetchmailrc</code>:
<source lang="shell">
#
# This rc file is run by /scripts/ddns.sh
# This file MUST have root:root and chmod 700

set postmaster "username";

poll "imap.mail.yahoo.com" protocol IMAP username "myaccount@yahoo.com" password "InsertPasswordHere" is "username" here keep folder "DDNS-Mailbox" ssl
</source>

UPDATE February 2021: Yahoo now requires you to create a secure app password. See [[#yahoo-app-pass|this section]].

You'll notice that it creates a file <code>/shares/Private/000__DDNS-ALERT__.txt</code>. The "000" is just to put it at the top of the directory listing. Also notice that I make it read-write for everyone so I can delete it from my webapp.

Set up permissions on all three files, and create the log file:
<source lang="sh">
touch /var/log/ddns.log
chown root:root /var/log/ddns.log
chmod 640 /var/log/ddns.log

chown root:root /scripts/ddns.sh
chmod 754 /scripts/ddns.sh

chown root:config /scripts/config/ddns-mailprocess.sh
chmod 750 /scripts/config/ddns-mailprocess.sh

chown root:root /scripts/config/ddns-fetchmailrc
chmod 700 /scripts/config/ddns-fetchmailrc
</source>

When you run <code>ddns.sh</code> as root it gives you a warning about running as root. This is okay.
<pre class="out">
fetchmail: WARNING: Running as root is discouraged.
</pre>

If permissions on <code>ddns-fetchmailrc</code> are not correct, you will get this failure message:
<pre class="out">
File /scripts/config/ddns-fetchmailrc must have no more than -rwx------ (0700) permissions.
</pre>

== Set Up Cron ==

Just for reference, here are the entries I made in my <code>/etc/crontab</code> file:
<source lang="sh">
# Crontabs to be run without 'run-parts'
#
# RUN AT NOON
0 12 * * * root /scripts/ddns.sh
0 12 * * * root /scripts/notifications.sh
# RUN EVERY 6 HOURS
1 0,6,12,18 * * * root /scripts/external-ip.sh
</source>

== <html><a name="yahoo-app-pass"></a></html>Yahoo App Password ==

As of February 2021, Yahoo changed that way third party apps can access it. Instead of using your normal password, you need to generate an app password.

# Login to Yahoo, click you user icon, and click Account Info.
# Click Account Security.
# Click Manage app passwords.
# Click the Select your app drop-down and select Other app.
# Type a name for the app then click Generate.
# Now you can copy the password and use it in your app. Once you navigate away from this page, you will not be able to retrieve the password again. You will have to generate another password.

Automatic Email and Text Notifications

2021-02-26T14:14:55Z

Beard: /* Email and Text Messaging with SSMTP */

These tutorials describe my method of automatic messaging via email and text (SMS) from my Linux servers.

== Required Packages ==

These packages are necessary for the all the following sections of this tutorial. In Debain, install them with <code>apt-get</code>:
<source lang="sh">
apt-get install ssmtp procmail fetchmail
</source>

== Directory Structure ==

Just for reference, here are the locations of the relevant files:
<source>
/
├── etc
│ └── ssmtp
│ └── ssmtp.conf
└── scripts
├── config
│ ├── accounts.conf
│ ├── ddns-fetchmailrc
│ └── ddns-mailprocess.sh
├── ddns.sh
├── email.sh
├── external-ip.sh
├── notifications.sh
└── sms.sh
</source>

And permissions:
<source lang="shell">
ls -l /scripts
</source>
<pre class="out">
drwxr-xr-x 4 root config 4096 Jun 20 08:52 config
-rwxr-xr-- 1 root root 260 Jun 20 08:40 ddns.sh
-rwxr-xr-- 1 root mailers 564 Apr 23 12:18 email.sh
-rwxr-xr-- 1 root root 529 Apr 27 07:56 external-ip.sh
-rwxr-xr-- 1 root root 3834 May 15 08:32 notifications.sh
-rwxr-xr-- 1 root texters 545 Apr 23 12:24 sms.sh
</pre>

<source lang="shell">
ls -l /scripts/config
</source>
<pre class="out">
-rwxr-x--- 1 root mailers 147 May 1 13:01 accounts.conf
-rwx------ 1 root root 246 May 21 09:49 ddns-fetchmailrc
-rwxr-x--- 1 root config 604 Jun 20 08:52 ddns-mailprocess.sh
</pre>

== Create Security Groups ==

I use group membership to control read access to certain files. You don't have to do this, but it was useful for me.

Create the groups:
<source lang="sh">
groupadd texters #allowed to sent text messages
groupadd mailers #allowed to send email messages
groupadd config #allowed to read other config files
</source>

You can add a user to all three groups like this:
<source lang="sh">
usermod -aG texters,mailers,config username
</source>

== Email and Text Messaging with SSMTP ==

First set up the <code>/etc/ssmtp/ssmtp.conf</code>. I use a dedicated Gmail account (named serveraccount@gmail.com in the example below) for all of my server messaging. When I receive an email from my server, it will look like it's coming from that Gmail.

Make a backup copy of the original config:
<source lang="sh">
cp /etc/ssmtp/ssmtp.conf /etc/ssmtp/ssmtp.conf.orig
</source>

Here are the contents of my modified <code>/etc/ssmtp/ssmtp.conf</code>. Replace the relevant values.
<source lang="sh">
#
# Config file for sSMTP sendmail
#
# The person who gets all mail for userids < 1000
# Make this empty to disable rewriting.
root=serveraccount

# The place where the mail goes. The actual machine name is required no
# MX records are consulted. Commonly mailhosts are named mail.domain.com
#mailhub=mail

# Where will the mail seem to come from?
rewriteDomain=gmail.com

# The full hostname
# This can be left as 'localhost'
hostname=localhost

# Are users allowed to set their own From: address?
# YES - Allow the user to specify their own From: address
# NO - Use the system generated From: address
FromLineOverride=YES

mailhub=smtp.gmail.com:587
UseStartTLS=YES
UseTLS=YES
AuthMethod=LOGIN
AuthUser=serveraccount@gmail.com
AuthPass=InsertPasswordHere
TLS_CA_File=/etc/pki/tls/certs/ca-bundle.crt
FromLineOverride=YES
</source>

Since the file contains a password, make sure the file is not readable to normal users.
<source lang="sh">
chown root:mail /etc/ssmtp/ssmtp.conf
chmod 640 /etc/ssmtp/ssmtp.conf
</source>

And because you don't have to remember this password, it would be a good idea to make it very long and complex (16+ characters; uppercase, lowercase, numbers, and special characters; no dictionary words).

You now need to log onto the serveraccount Gmail account and enable "less secure apps" at https://myaccount.google.com/lesssecureapps?pli=1 
[[File:Gmail-less-secure-app.png|frameless|600px]]

Here is more info about less secure apps: https://support.google.com/cloudidentity/answer/6260879?hl=en

If you're using Yahoo, see [[#yahoo-app-pass|this section]].

You should now be able use the <code>ssmtp</code> command line tool from your server. Most of the time, you will need to include a subject line. It's important that it follows the format below (capital 'S' on Subject, colon, space, YourSubject, two newlines):
<source lang="sh">
echo -e "Subject: Hi\n\nHello, world!" | ssmtp myaccount@yahoo.com
</source>

== Create a Secure Accounts File ==

For some of the automatic messaging, you need to store text and email accounts in a file. To figure out the destination address to send text (SMS) messages to your cell, look on your cell provider's website for the proper account/domain name. It will probably be something like "<your-phone-number>@<provider-domain>". [https://kb.sandisk.com/app/answers/detail/a_id/17056/~/list-of-mobile-carrier-gateway-addresses List of provider addresses]

Contents of my <code>/scripts/config/accounts.conf</code> file:
<source lang="sh">
#!/bin/bash
#
# Secure account information
# Permissions must be 750 root:mailers

smsto="17775551234@myprovider.net"
mailto="myaccount@yahoo.com"
</source>

Change the permissions on the file:
<source lang="sh">
chown root:mailers /scripts/config/accounts.conf
chmod 750 /scripts/config/accounts.conf
</source>

== Email Script ==

This script can be used to send an email message.

Contents of the file <code>/scripts/email.sh</code>:
<source lang="shell">
#!/bin/bash

# Send email message:
# Usage: $0 "<Subject>" "<Message>"

default_subject="Alert from Server (`date`)"

subject=""
message=""

case $# in
2)
subject="$1"
message="$2"
;;
1)
subject="$default_subject"
message="$1"
;;
*)
echo "Send Email Message:"
echo " Usage: `basename $0` \"Message\""
echo " `basename $0` \"Subject\" \"Message\""
exit 1
;;
esac

dir="$(cd $(dirname ${BASH_SOURCE[0]})&&pwd)"
. $dir/config/accounts.conf

echo -e "Subject: $subject\n\n$message" | /usr/sbin/ssmtp $mailto
</source>

Set up permissions:
<source lang="sh">
chown root:mailers /scripts/email.sh
chmod 754 /scripts/email.sh
</source>

You can create an alias so you can quickly run this from the command line:
<source lang="sh">
echo "alias email='/scripts/email.sh'" >>~/.bashrc
source ~/.bashrc
</source>

Usage:
<source lang="sh">
# Send message with default subject
email "This is a test message."

# Send message with a subject
email "Test Subject" "This is a test message."
</source>

== Text Script ==

This script can be used to send a text (SMS) message.

Contents of the file <code>/scripts/sms.sh</code>:
<source lang="shell">
#!/bin/bash

# Send SMS message:
# Usage: $0 "<Subject>" "<Message>"

default_subject="Alert"

subject=""
message=""

case $# in
2)
subject="$1"
message="$2"
;;
1)
subject="$default_subject"
message="$1"
;;
*)
echo "Send SMS Message:"
echo " Usage: `basename $0` \"Message\""
echo " `basename $0` \"Subject\" \"Message\""
exit 1
;;
esac

dir="$(cd $(dirname ${BASH_SOURCE[0]})&&pwd)"
. $dir/config/accounts.conf

echo -e "To: $smsto\nSubject: $subject\n\n$message" | /usr/sbin/ssmtp $smsto
</source>

Set up permissions:
<source lang="sh">
chown root:texters /scripts/sms.sh
chmod 754 /scripts/sms.sh
</source>

You can create an alias so you can quickly run this from the command line:
<source lang="sh">
echo "alias sms='/scripts/sms.sh'" >>~/.bashrc
source ~/.bashrc
</source>

Usage:
<source lang="sh">
# Send message with default subject
sms "This is a test message."

# Send message with a subject
sms "Test Subject" "This is a test message."
</source>

== Scheduled Notifications Script ==

One of my life improvement tasks was to organize chores into scheduled chore days and rely on text/email notification to remind me to do them.

This dramatically reduced the amount of time I spend working on chores, and the amount of effort I spend thinking about what needs to be done. I could barely get projects done because every day I was loading my task list with chores. Now I don't think about chores until I'm notified. When I think of new chores, new items for my inventory, or other things I need to be reminded of, I update my checklists. When I feel I can improve scheduling or consolidate chores, I update my notifications script.

This utilizes the Email Script and Text Script from the previous sections.

Contents of the file <code>/scripts/notifications.sh</code>:
<source lang="shell">
#!/bin/bash
#
# Send regular notifications.
# Currently set to run daily at NOON.
#

# Get current datetime values
dt=(`date +%Y\ %m\ %d\ %H\ %M\ %S\ %a\ %s\ %I\ %p\ %Z`)
y=$((10#${dt[0]})) #year
M=$((10#${dt[1]})) #month
d=$((10#${dt[2]})) #day
h=$((10#${dt[3]})) #hour(24)
m=$((10#${dt[4]})) #minute
s=$((10#${dt[5]})) #second
w=${dt[6]} #day of week (eg. Sun)
e=$((10#${dt[7]})) #epoch
t=$((10#${dt[8]})) #hour(12)
p=${dt[9]} #meridian (AM/PM)
z=${dt[10]} #timezone (eg. PDT)

# Schedule command when date ($1) matched regex ($2) with extra grep parameters ($3)
# Use parameter -P at $3 for perl regex: in case you need to use (str1|str2).
# Example: schedule $M$d "(115|21)" -P && sms "Subject" "Message"
# Don't use -P when you want a range of numbers including 2 or more digit numbers (ie. [1-15]).
schedule(){ echo "$1" | grep -wq $3 "$2";}
sms(){ /scripts/sms.sh "$1" "$2";}
eml(){ /scripts/email.sh "$1" "$2";}
notify(){ sms "$1" "$2";eml "$1" "$2";}

# =================================
# ==== Temporary Notifications ====
# =================================

# Dentist appointment
#schedule $M$d "58" && notify "Dentist" "Appointment 4:00pm 10/31/2017"

# =================================
# ====== Chore Notifications ======
# =================================

# LAUNDRY DAY
# Day before
schedule $w$d "Mon[1-7]" && notify "LAUNDRY DAY" "WORK: Check gas. HOME: Do laundry, put laundry away."
schedule $w$d "Mon(15|16|17|18|19|20|21)" -P && notify "LAUNDRY DAY" "WORK: Check gas. HOME: Do laundry, put laundry away."

# WEEKLY CLEANING DAY
schedule $w "Tue" && notify "WEEKLY CLEANING DAY" "WORK: Fill gas, shopping. HOME: Clean, litter, sweep/vac, fridge, trash, check meds."
# Day after
schedule $w "Wed" && notify "WEEKLY REMINDER" "Order meds if necessary."

# MONTHLY CLEANING DAY
schedule $w$d "Tue[1-7]" && notify "MONTHLY CLEANING DAY" "WORK: Car stuff. HOME: Dishes, kitchen, bathroom, dust, inventory."

# BUSINESS DAY
schedule $d "[1-4]" && notify "BUSINESS DAY" "Rent due before 5th (\$720). Fedloan, budgeting, donations, next-buy."

# TECH DAY
schedule $w$d "Mon[1-7]" && notify "TECH DAY" "WORK: Updates, phone, healthcheck, security scan, organize files. HOME: Organize Workstation/Laptop, USB drives."

# SHOPPING DAY
schedule $w$d "Wed[1-7]" && notify "SHOPPING DAY" "Shopping, carwash. Maybe do during lunch."

# GROOMING DAY
schedule $w$d "Sun[1-7]" && notify "GROOMING DAY" "Shave/trim, clip nails."
schedule $w$d "Sun(15|16|17|18|19|20|21)" -P && notify "GROOMING DAY" "Shave/trim, clip nails."

# ELIMINATION DAY
schedule $w$d "Sun(15|16|17|18|19|20|21)" -P && notify "ELIMINATION DAY" "Do at least one item on TO_ELIMINATE list."

# INVENTORY DAY
# Disabled. Inventory is now included in monthly cleaning day.
# schedule $w$d "Tue[1-7]" && notify "INVENTORY DAY" "Do home, car, and office inventory."

# =================================
# = Other Permanent Notifications =
# =================================

# Air filter replacement notifications
schedule $M$d "71" && notify "Air Filter" "Holmes HAP726: Replace HEPA filters (model:HAPF600,qty:2)"
schedule $M$d "[1|7]1" && notify "Air Filter" "Holmes HAP726: Replace Carbon filters (model:HAPF600,qty:2)"
</source>

Now set the permissions:
<source lang="sh">
chown root:root /scripts/external-ip.sh
chmod 754 /scripts/external-ip.sh
</source>

== Reporting External IP Address ==

My home server does not have a static IP address, so I use dynamic DNS. With my free DDNS service, I have to renew the domain name every 30 days. So if I forget to renew it, it will expire and I won't be able to access my server unless I know the IP address. As a contingency, I created a script that sends my external IP address to an email account every 6 hours. Then at least I would be able find out what my last IP was and use that to access my server.

Contents of the file <code>/scripts/external-ip.sh</code>:
<source lang="shell">
#!/bin/bash

log="/var/log/external-ip.log"
ipsrc="http://checkip.dyndns.org"
date="`date`"
addr="myaccount@yahoo.com"

ip=`curl -s --connect-timeout 3 $ipsrc 2>/dev/null|grep -Po "Current IP Address: .*?\<"|tr '<' '\0'`
echo "IP: $ip"

if [ -z "$ip" ];then
echo "$date ERROR: Could not get external IP from $ipsrc" >>$log
else
echo -e "Subject:[`hostname`] $date $ip" | /usr/sbin/ssmtp $addr
if [ "$?" = "0" ];then
echo "$date SUCCESS: $ip sent to $addr" >>$log
else
echo "$date ERROR: Could not send to $addr" >>$log
fi
fi
</source>

Now set the permissions:
<source lang="sh">
chown root:root /scripts/external-ip.sh
chmod 754 /scripts/external-ip.sh
</source>

This script appends to a log file <code>/var/log/external-ip.log</code>:
<source lang="sh">
touch /var/log/external-ip.log
chown root:root /var/log/external-ip.log
chmod 644 /var/log/external-ip.log
</source>

== Automatic Email Download ==

As mentioned in a previous section, I use free dynamic DNS which requires that I renew it manually every 30 days. I need to remind myself to do this. My provider sends an email notification a few days before it expires, but I hate email and I don't want it in my face all the time, certainly not in my phone.

The best solution I found was to retrieve the email automatically and send me a text message with only the subject line in the message. I eventually created a second method of notification: it generates a file in a place that I regularly go, the folder that contains all of my to-do lists.

Contents of the file <code>/scripts/ddns.sh</code>:
<source lang="shell">
#!/bin/bash
#
# This script is run by a cron job.

/usr/bin/fetchmail -N -d0 -f "/scripts/config/ddns-fetchmailrc" -m "/scripts/config/ddns-mailprocess.sh"

alertfile="/shares/Private/000__DDNS-ALERT__.txt"
if [ -e $alertfile ];then
chown root:root $alertfile
chmod 777 $alertfile
fi
</source>

Contents of the file <code>/scripts/config/ddns-mailprocess.sh</code>:
<source lang="shell">
#!/bin/bash
#
# This script is run by /scripts/ddns.sh

mailto="17775551234@myprovider.net"
date="`date`"
log="/var/log/ddns.log"
alertfile="/shares/Private/000__DDNS-ALERT__.txt"
sms="/scripts/sms.sh"

cat /dev/stdin | grep -i "^Subject:" | sed 's/Subject\://g' | $sms "DDNS" "`cat /dev/stdin` ( $date )" &&\
echo "$date - DDNS notification sent to $mailto" | tee -a $log | sed "s/$mailto/cell\ phone/g" >$alertfile &&\
chmod 777 $alertfile
</source>

Contents of the file <code>/scripts/config/ddns-fetchmailrc</code>:
<source lang="shell">
#
# This rc file is run by /scripts/ddns.sh
# This file MUST have root:root and chmod 700

set postmaster "username";

poll "imap.mail.yahoo.com" protocol IMAP username "myaccount@yahoo.com" password "InsertPasswordHere" is "username" here keep folder "DDNS-Mailbox" ssl
</source>

UPDATE February 2021: Yahoo now requires you to create a secure app password. See [[#yahoo-app-pass|this section]].

You'll notice that it creates a file <code>/shares/Private/000__DDNS-ALERT__.txt</code>. The "000" is just to put it at the top of the directory listing. Also notice that I make it read-write for everyone so I can delete it from my webapp.

Set up permissions on all three files, and create the log file:
<source lang="sh">
touch /var/log/ddns.log
chown root:root /var/log/ddns.log
chmod 640 /var/log/ddns.log

chown root:root /scripts/ddns.sh
chmod 754 /scripts/ddns.sh

chown root:config /scripts/config/ddns-mailprocess.sh
chmod 750 /scripts/config/ddns-mailprocess.sh

chown root:root /scripts/config/ddns-fetchmailrc
chmod 700 /scripts/config/ddns-fetchmailrc
</source>

When you run <code>ddns.sh</code> as root it gives you a warning about running as root. This is okay.
<pre class="out">
fetchmail: WARNING: Running as root is discouraged.
</pre>

If permissions on <code>ddns-fetchmailrc</code> are not correct, you will get this failure message:
<pre class="out">
File /scripts/config/ddns-fetchmailrc must have no more than -rwx------ (0700) permissions.
</pre>

== Set Up Cron ==

Just for reference, here are the entries I made in my <code>/etc/crontab</code> file:
<source lang="sh">
# Crontabs to be run without 'run-parts'
#
# RUN AT NOON
0 12 * * * root /scripts/ddns.sh
0 12 * * * root /scripts/notifications.sh
# RUN EVERY 6 HOURS
1 0,6,12,18 * * * root /scripts/external-ip.sh
</source>

== <html><a name="yahoo-app-pass"></a></html>Yahoo App Password ==

As of February 2021, Yahoo changed that way third party apps can access it. Instead of using your normal password, you need to generate an app password.

# Login to Yahoo, click you user icon, and click Account Info.
# Click Account Security.
# Click Manage app passwords.
# Click the Select your app drop-down and select Other app.
# Type a name for the app then click Generate.
# Now you can copy the password and use it in your app. Once you navigate away from this page, you will not be able to retrieve the password again. You will have to generate another password.

Automatic Email and Text Notifications

2021-02-26T14:14:07Z

Beard: /* Automatic Email Download */

Automatic Email and Text Notifications

2021-02-26T14:12:44Z

Beard: /* Yahoo App Password */

These tutorials describe my method of automatic messaging via email and text (SMS) from my Linux servers.

== Required Packages ==

These packages are necessary for the all the following sections of this tutorial. In Debain, install them with <code>apt-get</code>:
<source lang="sh">
apt-get install ssmtp procmail fetchmail
</source>

== Directory Structure ==

Just for reference, here are the locations of the relevant files:
<source>
/
├── etc
│ └── ssmtp
│ └── ssmtp.conf
└── scripts
├── config
│ ├── accounts.conf
│ ├── ddns-fetchmailrc
│ └── ddns-mailprocess.sh
├── ddns.sh
├── email.sh
├── external-ip.sh
├── notifications.sh
└── sms.sh
</source>

And permissions:
<source lang="shell">
ls -l /scripts
</source>
<pre class="out">
drwxr-xr-x 4 root config 4096 Jun 20 08:52 config
-rwxr-xr-- 1 root root 260 Jun 20 08:40 ddns.sh
-rwxr-xr-- 1 root mailers 564 Apr 23 12:18 email.sh
-rwxr-xr-- 1 root root 529 Apr 27 07:56 external-ip.sh
-rwxr-xr-- 1 root root 3834 May 15 08:32 notifications.sh
-rwxr-xr-- 1 root texters 545 Apr 23 12:24 sms.sh
</pre>

<source lang="shell">
ls -l /scripts/config
</source>
<pre class="out">
-rwxr-x--- 1 root mailers 147 May 1 13:01 accounts.conf
-rwx------ 1 root root 246 May 21 09:49 ddns-fetchmailrc
-rwxr-x--- 1 root config 604 Jun 20 08:52 ddns-mailprocess.sh
</pre>

== Create Security Groups ==

I use group membership to control read access to certain files. You don't have to do this, but it was useful for me.

Create the groups:
<source lang="sh">
groupadd texters #allowed to sent text messages
groupadd mailers #allowed to send email messages
groupadd config #allowed to read other config files
</source>

You can add a user to all three groups like this:
<source lang="sh">
usermod -aG texters,mailers,config username
</source>

== Email and Text Messaging with SSMTP ==

First set up the <code>/etc/ssmtp/ssmtp.conf</code>. I use a dedicated Gmail account (named serveraccount@gmail.com in the example below) for all of my server messaging. When I receive an email from my server, it will look like it's coming from that Gmail.

Make a backup copy of the original config:
<source lang="sh">
cp /etc/ssmtp/ssmtp.conf /etc/ssmtp/ssmtp.conf.orig
</source>

Here are the contents of my modified <code>/etc/ssmtp/ssmtp.conf</code>. Replace the relevant values.
<source lang="sh">
#
# Config file for sSMTP sendmail
#
# The person who gets all mail for userids < 1000
# Make this empty to disable rewriting.
root=serveraccount

# The place where the mail goes. The actual machine name is required no
# MX records are consulted. Commonly mailhosts are named mail.domain.com
#mailhub=mail

# Where will the mail seem to come from?
rewriteDomain=gmail.com

# The full hostname
# This can be left as 'localhost'
hostname=localhost

# Are users allowed to set their own From: address?
# YES - Allow the user to specify their own From: address
# NO - Use the system generated From: address
FromLineOverride=YES

mailhub=smtp.gmail.com:587
UseStartTLS=YES
UseTLS=YES
AuthMethod=LOGIN
AuthUser=serveraccount@gmail.com
AuthPass=InsertPasswordHere
TLS_CA_File=/etc/pki/tls/certs/ca-bundle.crt
FromLineOverride=YES
</source>

Since the file contains a password, make sure the file is not readable to normal users.
<source lang="sh">
chown root:mail /etc/ssmtp/ssmtp.conf
chmod 640 /etc/ssmtp/ssmtp.conf
</source>

And because you don't have to remember this password, it would be a good idea to make it very long and complex (16+ characters; uppercase, lowercase, numbers, and special characters; no dictionary words).

You now need to log onto the serveraccount Gmail account and enable "less secure apps" at https://myaccount.google.com/lesssecureapps?pli=1 
[[File:Gmail-less-secure-app.png|frameless|600px]]

Here is more info about less secure apps: https://support.google.com/cloudidentity/answer/6260879?hl=en

You should now be able use the <code>ssmtp</code> command line tool from your server. Most of the time, you will need to include a subject line. It's important that it follows the format below (capital 'S' on Subject, colon, space, YourSubject, two newlines):
<source lang="sh">
echo -e "Subject: Hi\n\nHello, world!" | ssmtp myaccount@yahoo.com
</source>

== Create a Secure Accounts File ==

For some of the automatic messaging, you need to store text and email accounts in a file. To figure out the destination address to send text (SMS) messages to your cell, look on your cell provider's website for the proper account/domain name. It will probably be something like "<your-phone-number>@<provider-domain>". [https://kb.sandisk.com/app/answers/detail/a_id/17056/~/list-of-mobile-carrier-gateway-addresses List of provider addresses]

Contents of my <code>/scripts/config/accounts.conf</code> file:
<source lang="sh">
#!/bin/bash
#
# Secure account information
# Permissions must be 750 root:mailers

smsto="17775551234@myprovider.net"
mailto="myaccount@yahoo.com"
</source>

Change the permissions on the file:
<source lang="sh">
chown root:mailers /scripts/config/accounts.conf
chmod 750 /scripts/config/accounts.conf
</source>

== Email Script ==

This script can be used to send an email message.

Contents of the file <code>/scripts/email.sh</code>:
<source lang="shell">
#!/bin/bash

# Send email message:
# Usage: $0 "<Subject>" "<Message>"

default_subject="Alert from Server (`date`)"

subject=""
message=""

case $# in
2)
subject="$1"
message="$2"
;;
1)
subject="$default_subject"
message="$1"
;;
*)
echo "Send Email Message:"
echo " Usage: `basename $0` \"Message\""
echo " `basename $0` \"Subject\" \"Message\""
exit 1
;;
esac

dir="$(cd $(dirname ${BASH_SOURCE[0]})&&pwd)"
. $dir/config/accounts.conf

echo -e "Subject: $subject\n\n$message" | /usr/sbin/ssmtp $mailto
</source>

Set up permissions:
<source lang="sh">
chown root:mailers /scripts/email.sh
chmod 754 /scripts/email.sh
</source>

You can create an alias so you can quickly run this from the command line:
<source lang="sh">
echo "alias email='/scripts/email.sh'" >>~/.bashrc
source ~/.bashrc
</source>

Usage:
<source lang="sh">
# Send message with default subject
email "This is a test message."

# Send message with a subject
email "Test Subject" "This is a test message."
</source>

== Text Script ==

This script can be used to send a text (SMS) message.

Contents of the file <code>/scripts/sms.sh</code>:
<source lang="shell">
#!/bin/bash

# Send SMS message:
# Usage: $0 "<Subject>" "<Message>"

default_subject="Alert"

subject=""
message=""

case $# in
2)
subject="$1"
message="$2"
;;
1)
subject="$default_subject"
message="$1"
;;
*)
echo "Send SMS Message:"
echo " Usage: `basename $0` \"Message\""
echo " `basename $0` \"Subject\" \"Message\""
exit 1
;;
esac

dir="$(cd $(dirname ${BASH_SOURCE[0]})&&pwd)"
. $dir/config/accounts.conf

echo -e "To: $smsto\nSubject: $subject\n\n$message" | /usr/sbin/ssmtp $smsto
</source>

Set up permissions:
<source lang="sh">
chown root:texters /scripts/sms.sh
chmod 754 /scripts/sms.sh
</source>

You can create an alias so you can quickly run this from the command line:
<source lang="sh">
echo "alias sms='/scripts/sms.sh'" >>~/.bashrc
source ~/.bashrc
</source>

Usage:
<source lang="sh">
# Send message with default subject
sms "This is a test message."

# Send message with a subject
sms "Test Subject" "This is a test message."
</source>

== Scheduled Notifications Script ==

One of my life improvement tasks was to organize chores into scheduled chore days and rely on text/email notification to remind me to do them.

This dramatically reduced the amount of time I spend working on chores, and the amount of effort I spend thinking about what needs to be done. I could barely get projects done because every day I was loading my task list with chores. Now I don't think about chores until I'm notified. When I think of new chores, new items for my inventory, or other things I need to be reminded of, I update my checklists. When I feel I can improve scheduling or consolidate chores, I update my notifications script.

This utilizes the Email Script and Text Script from the previous sections.

Contents of the file <code>/scripts/notifications.sh</code>:
<source lang="shell">
#!/bin/bash
#
# Send regular notifications.
# Currently set to run daily at NOON.
#

# Get current datetime values
dt=(`date +%Y\ %m\ %d\ %H\ %M\ %S\ %a\ %s\ %I\ %p\ %Z`)
y=$((10#${dt[0]})) #year
M=$((10#${dt[1]})) #month
d=$((10#${dt[2]})) #day
h=$((10#${dt[3]})) #hour(24)
m=$((10#${dt[4]})) #minute
s=$((10#${dt[5]})) #second
w=${dt[6]} #day of week (eg. Sun)
e=$((10#${dt[7]})) #epoch
t=$((10#${dt[8]})) #hour(12)
p=${dt[9]} #meridian (AM/PM)
z=${dt[10]} #timezone (eg. PDT)

# Schedule command when date ($1) matched regex ($2) with extra grep parameters ($3)
# Use parameter -P at $3 for perl regex: in case you need to use (str1|str2).
# Example: schedule $M$d "(115|21)" -P && sms "Subject" "Message"
# Don't use -P when you want a range of numbers including 2 or more digit numbers (ie. [1-15]).
schedule(){ echo "$1" | grep -wq $3 "$2";}
sms(){ /scripts/sms.sh "$1" "$2";}
eml(){ /scripts/email.sh "$1" "$2";}
notify(){ sms "$1" "$2";eml "$1" "$2";}

# =================================
# ==== Temporary Notifications ====
# =================================

# Dentist appointment
#schedule $M$d "58" && notify "Dentist" "Appointment 4:00pm 10/31/2017"

# =================================
# ====== Chore Notifications ======
# =================================

# LAUNDRY DAY
# Day before
schedule $w$d "Mon[1-7]" && notify "LAUNDRY DAY" "WORK: Check gas. HOME: Do laundry, put laundry away."
schedule $w$d "Mon(15|16|17|18|19|20|21)" -P && notify "LAUNDRY DAY" "WORK: Check gas. HOME: Do laundry, put laundry away."

# WEEKLY CLEANING DAY
schedule $w "Tue" && notify "WEEKLY CLEANING DAY" "WORK: Fill gas, shopping. HOME: Clean, litter, sweep/vac, fridge, trash, check meds."
# Day after
schedule $w "Wed" && notify "WEEKLY REMINDER" "Order meds if necessary."

# MONTHLY CLEANING DAY
schedule $w$d "Tue[1-7]" && notify "MONTHLY CLEANING DAY" "WORK: Car stuff. HOME: Dishes, kitchen, bathroom, dust, inventory."

# BUSINESS DAY
schedule $d "[1-4]" && notify "BUSINESS DAY" "Rent due before 5th (\$720). Fedloan, budgeting, donations, next-buy."

# TECH DAY
schedule $w$d "Mon[1-7]" && notify "TECH DAY" "WORK: Updates, phone, healthcheck, security scan, organize files. HOME: Organize Workstation/Laptop, USB drives."

# SHOPPING DAY
schedule $w$d "Wed[1-7]" && notify "SHOPPING DAY" "Shopping, carwash. Maybe do during lunch."

# GROOMING DAY
schedule $w$d "Sun[1-7]" && notify "GROOMING DAY" "Shave/trim, clip nails."
schedule $w$d "Sun(15|16|17|18|19|20|21)" -P && notify "GROOMING DAY" "Shave/trim, clip nails."

# ELIMINATION DAY
schedule $w$d "Sun(15|16|17|18|19|20|21)" -P && notify "ELIMINATION DAY" "Do at least one item on TO_ELIMINATE list."

# INVENTORY DAY
# Disabled. Inventory is now included in monthly cleaning day.
# schedule $w$d "Tue[1-7]" && notify "INVENTORY DAY" "Do home, car, and office inventory."

# =================================
# = Other Permanent Notifications =
# =================================

# Air filter replacement notifications
schedule $M$d "71" && notify "Air Filter" "Holmes HAP726: Replace HEPA filters (model:HAPF600,qty:2)"
schedule $M$d "[1|7]1" && notify "Air Filter" "Holmes HAP726: Replace Carbon filters (model:HAPF600,qty:2)"
</source>

Now set the permissions:
<source lang="sh">
chown root:root /scripts/external-ip.sh
chmod 754 /scripts/external-ip.sh
</source>

== Reporting External IP Address ==

My home server does not have a static IP address, so I use dynamic DNS. With my free DDNS service, I have to renew the domain name every 30 days. So if I forget to renew it, it will expire and I won't be able to access my server unless I know the IP address. As a contingency, I created a script that sends my external IP address to an email account every 6 hours. Then at least I would be able find out what my last IP was and use that to access my server.

Contents of the file <code>/scripts/external-ip.sh</code>:
<source lang="shell">
#!/bin/bash

log="/var/log/external-ip.log"
ipsrc="http://checkip.dyndns.org"
date="`date`"
addr="myaccount@yahoo.com"

ip=`curl -s --connect-timeout 3 $ipsrc 2>/dev/null|grep -Po "Current IP Address: .*?\<"|tr '<' '\0'`
echo "IP: $ip"

if [ -z "$ip" ];then
echo "$date ERROR: Could not get external IP from $ipsrc" >>$log
else
echo -e "Subject:[`hostname`] $date $ip" | /usr/sbin/ssmtp $addr
if [ "$?" = "0" ];then
echo "$date SUCCESS: $ip sent to $addr" >>$log
else
echo "$date ERROR: Could not send to $addr" >>$log
fi
fi
</source>

Now set the permissions:
<source lang="sh">
chown root:root /scripts/external-ip.sh
chmod 754 /scripts/external-ip.sh
</source>

This script appends to a log file <code>/var/log/external-ip.log</code>:
<source lang="sh">
touch /var/log/external-ip.log
chown root:root /var/log/external-ip.log
chmod 644 /var/log/external-ip.log
</source>

== Automatic Email Download ==

As mentioned in a previous section, I use free dynamic DNS which requires that I renew it manually every 30 days. I need to remind myself to do this. My provider sends an email notification a few days before it expires, but I hate email and I don't want it in my face all the time, certainly not in my phone.

The best solution I found was to retrieve the email automatically and send me a text message with only the subject line in the message. I eventually created a second method of notification: it generates a file in a place that I regularly go, the folder that contains all of my to-do lists.

Contents of the file <code>/scripts/ddns.sh</code>:
<source lang="shell">
#!/bin/bash
#
# This script is run by a cron job.

/usr/bin/fetchmail -N -d0 -f "/scripts/config/ddns-fetchmailrc" -m "/scripts/config/ddns-mailprocess.sh"

alertfile="/shares/Private/000__DDNS-ALERT__.txt"
if [ -e $alertfile ];then
chown root:root $alertfile
chmod 777 $alertfile
fi
</source>

Contents of the file <code>/scripts/config/ddns-mailprocess.sh</code>:
<source lang="shell">
#!/bin/bash
#
# This script is run by /scripts/ddns.sh

mailto="17775551234@myprovider.net"
date="`date`"
log="/var/log/ddns.log"
alertfile="/shares/Private/000__DDNS-ALERT__.txt"
sms="/scripts/sms.sh"

cat /dev/stdin | grep -i "^Subject:" | sed 's/Subject\://g' | $sms "DDNS" "`cat /dev/stdin` ( $date )" &&\
echo "$date - DDNS notification sent to $mailto" | tee -a $log | sed "s/$mailto/cell\ phone/g" >$alertfile &&\
chmod 777 $alertfile
</source>

Contents of the file <code>/scripts/config/ddns-fetchmailrc</code>:
<source lang="shell">
#
# This rc file is run by /scripts/ddns.sh
# This file MUST have root:root and chmod 700

set postmaster "username";

poll "imap.mail.yahoo.com" protocol IMAP username "myaccount@yahoo.com" password "InsertPasswordHere" is "username" here keep folder "DDNS-Mailbox" ssl
</source>

You'll notice that it creates a file <code>/shares/Private/000__DDNS-ALERT__.txt</code>. The "000" is just to put it at the top of the directory listing. Also notice that I make it read-write for everyone so I can delete it from my webapp.

Set up permissions on all three files, and create the log file:
<source lang="sh">
touch /var/log/ddns.log
chown root:root /var/log/ddns.log
chmod 640 /var/log/ddns.log

chown root:root /scripts/ddns.sh
chmod 754 /scripts/ddns.sh

chown root:config /scripts/config/ddns-mailprocess.sh
chmod 750 /scripts/config/ddns-mailprocess.sh

chown root:root /scripts/config/ddns-fetchmailrc
chmod 700 /scripts/config/ddns-fetchmailrc
</source>

UPDATE February 2021: Yahoo now requires you to create a secure app password. See [[#yahoo-app-pass|this section]].

When you run <code>ddns.sh</code> as root it gives you a warning about running as root. This is okay.
<pre class="out">
fetchmail: WARNING: Running as root is discouraged.
</pre>

If permissions on <code>ddns-fetchmailrc</code> are not correct, you will get this failure message:
<pre class="out">
File /scripts/config/ddns-fetchmailrc must have no more than -rwx------ (0700) permissions.
</pre>

== Set Up Cron ==

Just for reference, here are the entries I made in my <code>/etc/crontab</code> file:
<source lang="sh">
# Crontabs to be run without 'run-parts'
#
# RUN AT NOON
0 12 * * * root /scripts/ddns.sh
0 12 * * * root /scripts/notifications.sh
# RUN EVERY 6 HOURS
1 0,6,12,18 * * * root /scripts/external-ip.sh
</source>

== <html><a name="yahoo-app-pass"></a></html>Yahoo App Password ==

As of February 2021, Yahoo changed that way third party apps can access it. Instead of using your normal password, you need to generate an app password.

# Login to Yahoo, click you user icon, and click Account Info.
# Click Account Security.
# Click Manage app passwords.
# Click the Select your app drop-down and select Other app.
# Type a name for the app then click Generate.
# Now you can copy the password and use it in your app. Once you navigate away from this page, you will not be able to retrieve the password again. You will have to generate another password.

Automatic Email and Text Notifications

2021-02-26T14:12:09Z

Beard: /* Yahoo App Password */

These tutorials describe my method of automatic messaging via email and text (SMS) from my Linux servers.

== Required Packages ==

These packages are necessary for the all the following sections of this tutorial. In Debain, install them with <code>apt-get</code>:
<source lang="sh">
apt-get install ssmtp procmail fetchmail
</source>

== Directory Structure ==

Just for reference, here are the locations of the relevant files:
<source>
/
├── etc
│ └── ssmtp
│ └── ssmtp.conf
└── scripts
├── config
│ ├── accounts.conf
│ ├── ddns-fetchmailrc
│ └── ddns-mailprocess.sh
├── ddns.sh
├── email.sh
├── external-ip.sh
├── notifications.sh
└── sms.sh
</source>

And permissions:
<source lang="shell">
ls -l /scripts
</source>
<pre class="out">
drwxr-xr-x 4 root config 4096 Jun 20 08:52 config
-rwxr-xr-- 1 root root 260 Jun 20 08:40 ddns.sh
-rwxr-xr-- 1 root mailers 564 Apr 23 12:18 email.sh
-rwxr-xr-- 1 root root 529 Apr 27 07:56 external-ip.sh
-rwxr-xr-- 1 root root 3834 May 15 08:32 notifications.sh
-rwxr-xr-- 1 root texters 545 Apr 23 12:24 sms.sh
</pre>

<source lang="shell">
ls -l /scripts/config
</source>
<pre class="out">
-rwxr-x--- 1 root mailers 147 May 1 13:01 accounts.conf
-rwx------ 1 root root 246 May 21 09:49 ddns-fetchmailrc
-rwxr-x--- 1 root config 604 Jun 20 08:52 ddns-mailprocess.sh
</pre>

== Create Security Groups ==

I use group membership to control read access to certain files. You don't have to do this, but it was useful for me.

Create the groups:
<source lang="sh">
groupadd texters #allowed to sent text messages
groupadd mailers #allowed to send email messages
groupadd config #allowed to read other config files
</source>

You can add a user to all three groups like this:
<source lang="sh">
usermod -aG texters,mailers,config username
</source>

== Email and Text Messaging with SSMTP ==

First set up the <code>/etc/ssmtp/ssmtp.conf</code>. I use a dedicated Gmail account (named serveraccount@gmail.com in the example below) for all of my server messaging. When I receive an email from my server, it will look like it's coming from that Gmail.

Make a backup copy of the original config:
<source lang="sh">
cp /etc/ssmtp/ssmtp.conf /etc/ssmtp/ssmtp.conf.orig
</source>

Here are the contents of my modified <code>/etc/ssmtp/ssmtp.conf</code>. Replace the relevant values.
<source lang="sh">
#
# Config file for sSMTP sendmail
#
# The person who gets all mail for userids < 1000
# Make this empty to disable rewriting.
root=serveraccount

# The place where the mail goes. The actual machine name is required no
# MX records are consulted. Commonly mailhosts are named mail.domain.com
#mailhub=mail

# Where will the mail seem to come from?
rewriteDomain=gmail.com

# The full hostname
# This can be left as 'localhost'
hostname=localhost

# Are users allowed to set their own From: address?
# YES - Allow the user to specify their own From: address
# NO - Use the system generated From: address
FromLineOverride=YES

mailhub=smtp.gmail.com:587
UseStartTLS=YES
UseTLS=YES
AuthMethod=LOGIN
AuthUser=serveraccount@gmail.com
AuthPass=InsertPasswordHere
TLS_CA_File=/etc/pki/tls/certs/ca-bundle.crt
FromLineOverride=YES
</source>

Since the file contains a password, make sure the file is not readable to normal users.
<source lang="sh">
chown root:mail /etc/ssmtp/ssmtp.conf
chmod 640 /etc/ssmtp/ssmtp.conf
</source>

And because you don't have to remember this password, it would be a good idea to make it very long and complex (16+ characters; uppercase, lowercase, numbers, and special characters; no dictionary words).

You now need to log onto the serveraccount Gmail account and enable "less secure apps" at https://myaccount.google.com/lesssecureapps?pli=1 
[[File:Gmail-less-secure-app.png|frameless|600px]]

Here is more info about less secure apps: https://support.google.com/cloudidentity/answer/6260879?hl=en

You should now be able use the <code>ssmtp</code> command line tool from your server. Most of the time, you will need to include a subject line. It's important that it follows the format below (capital 'S' on Subject, colon, space, YourSubject, two newlines):
<source lang="sh">
echo -e "Subject: Hi\n\nHello, world!" | ssmtp myaccount@yahoo.com
</source>

== Create a Secure Accounts File ==

For some of the automatic messaging, you need to store text and email accounts in a file. To figure out the destination address to send text (SMS) messages to your cell, look on your cell provider's website for the proper account/domain name. It will probably be something like "<your-phone-number>@<provider-domain>". [https://kb.sandisk.com/app/answers/detail/a_id/17056/~/list-of-mobile-carrier-gateway-addresses List of provider addresses]

Contents of my <code>/scripts/config/accounts.conf</code> file:
<source lang="sh">
#!/bin/bash
#
# Secure account information
# Permissions must be 750 root:mailers

smsto="17775551234@myprovider.net"
mailto="myaccount@yahoo.com"
</source>

Change the permissions on the file:
<source lang="sh">
chown root:mailers /scripts/config/accounts.conf
chmod 750 /scripts/config/accounts.conf
</source>

== Email Script ==

This script can be used to send an email message.

Contents of the file <code>/scripts/email.sh</code>:
<source lang="shell">
#!/bin/bash

# Send email message:
# Usage: $0 "<Subject>" "<Message>"

default_subject="Alert from Server (`date`)"

subject=""
message=""

case $# in
2)
subject="$1"
message="$2"
;;
1)
subject="$default_subject"
message="$1"
;;
*)
echo "Send Email Message:"
echo " Usage: `basename $0` \"Message\""
echo " `basename $0` \"Subject\" \"Message\""
exit 1
;;
esac

dir="$(cd $(dirname ${BASH_SOURCE[0]})&&pwd)"
. $dir/config/accounts.conf

echo -e "Subject: $subject\n\n$message" | /usr/sbin/ssmtp $mailto
</source>

Set up permissions:
<source lang="sh">
chown root:mailers /scripts/email.sh
chmod 754 /scripts/email.sh
</source>

You can create an alias so you can quickly run this from the command line:
<source lang="sh">
echo "alias email='/scripts/email.sh'" >>~/.bashrc
source ~/.bashrc
</source>

Usage:
<source lang="sh">
# Send message with default subject
email "This is a test message."

# Send message with a subject
email "Test Subject" "This is a test message."
</source>

== Text Script ==

This script can be used to send a text (SMS) message.

Contents of the file <code>/scripts/sms.sh</code>:
<source lang="shell">
#!/bin/bash

# Send SMS message:
# Usage: $0 "<Subject>" "<Message>"

default_subject="Alert"

subject=""
message=""

case $# in
2)
subject="$1"
message="$2"
;;
1)
subject="$default_subject"
message="$1"
;;
*)
echo "Send SMS Message:"
echo " Usage: `basename $0` \"Message\""
echo " `basename $0` \"Subject\" \"Message\""
exit 1
;;
esac

dir="$(cd $(dirname ${BASH_SOURCE[0]})&&pwd)"
. $dir/config/accounts.conf

echo -e "To: $smsto\nSubject: $subject\n\n$message" | /usr/sbin/ssmtp $smsto
</source>

Set up permissions:
<source lang="sh">
chown root:texters /scripts/sms.sh
chmod 754 /scripts/sms.sh
</source>

You can create an alias so you can quickly run this from the command line:
<source lang="sh">
echo "alias sms='/scripts/sms.sh'" >>~/.bashrc
source ~/.bashrc
</source>

Usage:
<source lang="sh">
# Send message with default subject
sms "This is a test message."

# Send message with a subject
sms "Test Subject" "This is a test message."
</source>

== Scheduled Notifications Script ==

One of my life improvement tasks was to organize chores into scheduled chore days and rely on text/email notification to remind me to do them.

This dramatically reduced the amount of time I spend working on chores, and the amount of effort I spend thinking about what needs to be done. I could barely get projects done because every day I was loading my task list with chores. Now I don't think about chores until I'm notified. When I think of new chores, new items for my inventory, or other things I need to be reminded of, I update my checklists. When I feel I can improve scheduling or consolidate chores, I update my notifications script.

This utilizes the Email Script and Text Script from the previous sections.

Contents of the file <code>/scripts/notifications.sh</code>:
<source lang="shell">
#!/bin/bash
#
# Send regular notifications.
# Currently set to run daily at NOON.
#

# Get current datetime values
dt=(`date +%Y\ %m\ %d\ %H\ %M\ %S\ %a\ %s\ %I\ %p\ %Z`)
y=$((10#${dt[0]})) #year
M=$((10#${dt[1]})) #month
d=$((10#${dt[2]})) #day
h=$((10#${dt[3]})) #hour(24)
m=$((10#${dt[4]})) #minute
s=$((10#${dt[5]})) #second
w=${dt[6]} #day of week (eg. Sun)
e=$((10#${dt[7]})) #epoch
t=$((10#${dt[8]})) #hour(12)
p=${dt[9]} #meridian (AM/PM)
z=${dt[10]} #timezone (eg. PDT)

# Schedule command when date ($1) matched regex ($2) with extra grep parameters ($3)
# Use parameter -P at $3 for perl regex: in case you need to use (str1|str2).
# Example: schedule $M$d "(115|21)" -P && sms "Subject" "Message"
# Don't use -P when you want a range of numbers including 2 or more digit numbers (ie. [1-15]).
schedule(){ echo "$1" | grep -wq $3 "$2";}
sms(){ /scripts/sms.sh "$1" "$2";}
eml(){ /scripts/email.sh "$1" "$2";}
notify(){ sms "$1" "$2";eml "$1" "$2";}

# =================================
# ==== Temporary Notifications ====
# =================================

# Dentist appointment
#schedule $M$d "58" && notify "Dentist" "Appointment 4:00pm 10/31/2017"

# =================================
# ====== Chore Notifications ======
# =================================

# LAUNDRY DAY
# Day before
schedule $w$d "Mon[1-7]" && notify "LAUNDRY DAY" "WORK: Check gas. HOME: Do laundry, put laundry away."
schedule $w$d "Mon(15|16|17|18|19|20|21)" -P && notify "LAUNDRY DAY" "WORK: Check gas. HOME: Do laundry, put laundry away."

# WEEKLY CLEANING DAY
schedule $w "Tue" && notify "WEEKLY CLEANING DAY" "WORK: Fill gas, shopping. HOME: Clean, litter, sweep/vac, fridge, trash, check meds."
# Day after
schedule $w "Wed" && notify "WEEKLY REMINDER" "Order meds if necessary."

# MONTHLY CLEANING DAY
schedule $w$d "Tue[1-7]" && notify "MONTHLY CLEANING DAY" "WORK: Car stuff. HOME: Dishes, kitchen, bathroom, dust, inventory."

# BUSINESS DAY
schedule $d "[1-4]" && notify "BUSINESS DAY" "Rent due before 5th (\$720). Fedloan, budgeting, donations, next-buy."

# TECH DAY
schedule $w$d "Mon[1-7]" && notify "TECH DAY" "WORK: Updates, phone, healthcheck, security scan, organize files. HOME: Organize Workstation/Laptop, USB drives."

# SHOPPING DAY
schedule $w$d "Wed[1-7]" && notify "SHOPPING DAY" "Shopping, carwash. Maybe do during lunch."

# GROOMING DAY
schedule $w$d "Sun[1-7]" && notify "GROOMING DAY" "Shave/trim, clip nails."
schedule $w$d "Sun(15|16|17|18|19|20|21)" -P && notify "GROOMING DAY" "Shave/trim, clip nails."

# ELIMINATION DAY
schedule $w$d "Sun(15|16|17|18|19|20|21)" -P && notify "ELIMINATION DAY" "Do at least one item on TO_ELIMINATE list."

# INVENTORY DAY
# Disabled. Inventory is now included in monthly cleaning day.
# schedule $w$d "Tue[1-7]" && notify "INVENTORY DAY" "Do home, car, and office inventory."

# =================================
# = Other Permanent Notifications =
# =================================

# Air filter replacement notifications
schedule $M$d "71" && notify "Air Filter" "Holmes HAP726: Replace HEPA filters (model:HAPF600,qty:2)"
schedule $M$d "[1|7]1" && notify "Air Filter" "Holmes HAP726: Replace Carbon filters (model:HAPF600,qty:2)"
</source>

Now set the permissions:
<source lang="sh">
chown root:root /scripts/external-ip.sh
chmod 754 /scripts/external-ip.sh
</source>

== Reporting External IP Address ==

My home server does not have a static IP address, so I use dynamic DNS. With my free DDNS service, I have to renew the domain name every 30 days. So if I forget to renew it, it will expire and I won't be able to access my server unless I know the IP address. As a contingency, I created a script that sends my external IP address to an email account every 6 hours. Then at least I would be able find out what my last IP was and use that to access my server.

Contents of the file <code>/scripts/external-ip.sh</code>:
<source lang="shell">
#!/bin/bash

log="/var/log/external-ip.log"
ipsrc="http://checkip.dyndns.org"
date="`date`"
addr="myaccount@yahoo.com"

ip=`curl -s --connect-timeout 3 $ipsrc 2>/dev/null|grep -Po "Current IP Address: .*?\<"|tr '<' '\0'`
echo "IP: $ip"

if [ -z "$ip" ];then
echo "$date ERROR: Could not get external IP from $ipsrc" >>$log
else
echo -e "Subject:[`hostname`] $date $ip" | /usr/sbin/ssmtp $addr
if [ "$?" = "0" ];then
echo "$date SUCCESS: $ip sent to $addr" >>$log
else
echo "$date ERROR: Could not send to $addr" >>$log
fi
fi
</source>

Now set the permissions:
<source lang="sh">
chown root:root /scripts/external-ip.sh
chmod 754 /scripts/external-ip.sh
</source>

This script appends to a log file <code>/var/log/external-ip.log</code>:
<source lang="sh">
touch /var/log/external-ip.log
chown root:root /var/log/external-ip.log
chmod 644 /var/log/external-ip.log
</source>

== Automatic Email Download ==

As mentioned in a previous section, I use free dynamic DNS which requires that I renew it manually every 30 days. I need to remind myself to do this. My provider sends an email notification a few days before it expires, but I hate email and I don't want it in my face all the time, certainly not in my phone.

The best solution I found was to retrieve the email automatically and send me a text message with only the subject line in the message. I eventually created a second method of notification: it generates a file in a place that I regularly go, the folder that contains all of my to-do lists.

Contents of the file <code>/scripts/ddns.sh</code>:
<source lang="shell">
#!/bin/bash
#
# This script is run by a cron job.

/usr/bin/fetchmail -N -d0 -f "/scripts/config/ddns-fetchmailrc" -m "/scripts/config/ddns-mailprocess.sh"

alertfile="/shares/Private/000__DDNS-ALERT__.txt"
if [ -e $alertfile ];then
chown root:root $alertfile
chmod 777 $alertfile
fi
</source>

Contents of the file <code>/scripts/config/ddns-mailprocess.sh</code>:
<source lang="shell">
#!/bin/bash
#
# This script is run by /scripts/ddns.sh

mailto="17775551234@myprovider.net"
date="`date`"
log="/var/log/ddns.log"
alertfile="/shares/Private/000__DDNS-ALERT__.txt"
sms="/scripts/sms.sh"

cat /dev/stdin | grep -i "^Subject:" | sed 's/Subject\://g' | $sms "DDNS" "`cat /dev/stdin` ( $date )" &&\
echo "$date - DDNS notification sent to $mailto" | tee -a $log | sed "s/$mailto/cell\ phone/g" >$alertfile &&\
chmod 777 $alertfile
</source>

Contents of the file <code>/scripts/config/ddns-fetchmailrc</code>:
<source lang="shell">
#
# This rc file is run by /scripts/ddns.sh
# This file MUST have root:root and chmod 700

set postmaster "username";

poll "imap.mail.yahoo.com" protocol IMAP username "myaccount@yahoo.com" password "InsertPasswordHere" is "username" here keep folder "DDNS-Mailbox" ssl
</source>

You'll notice that it creates a file <code>/shares/Private/000__DDNS-ALERT__.txt</code>. The "000" is just to put it at the top of the directory listing. Also notice that I make it read-write for everyone so I can delete it from my webapp.

Set up permissions on all three files, and create the log file:
<source lang="sh">
touch /var/log/ddns.log
chown root:root /var/log/ddns.log
chmod 640 /var/log/ddns.log

chown root:root /scripts/ddns.sh
chmod 754 /scripts/ddns.sh

chown root:config /scripts/config/ddns-mailprocess.sh
chmod 750 /scripts/config/ddns-mailprocess.sh

chown root:root /scripts/config/ddns-fetchmailrc
chmod 700 /scripts/config/ddns-fetchmailrc
</source>

UPDATE February 2021: Yahoo now requires you to create a secure app password. See [[#yahoo-app-pass|this section]].

When you run <code>ddns.sh</code> as root it gives you a warning about running as root. This is okay.
<pre class="out">
fetchmail: WARNING: Running as root is discouraged.
</pre>

If permissions on <code>ddns-fetchmailrc</code> are not correct, you will get this failure message:
<pre class="out">
File /scripts/config/ddns-fetchmailrc must have no more than -rwx------ (0700) permissions.
</pre>

== Set Up Cron ==

Just for reference, here are the entries I made in my <code>/etc/crontab</code> file:
<source lang="sh">
# Crontabs to be run without 'run-parts'
#
# RUN AT NOON
0 12 * * * root /scripts/ddns.sh
0 12 * * * root /scripts/notifications.sh
# RUN EVERY 6 HOURS
1 0,6,12,18 * * * root /scripts/external-ip.sh
</source>

== <a name="yahoo-app-pass"></a>Yahoo App Password ==

As of February 2021, Yahoo changed that way third party apps can access it. Instead of using your normal password, you need to generate an app password.

# Login to Yahoo, click you user icon, and click Account Info.
# Click Account Security.
# Click Manage app passwords.
# Click the Select your app drop-down and select Other app.
# Type a name for the app then click Generate.
# Now you can copy the password and use it in your app. Once you navigate away from this page, you will not be able to retrieve the password again. You will have to generate another password.

Automatic Email and Text Notifications

2021-02-26T14:11:26Z

Beard: /* Set Up Cron */

These tutorials describe my method of automatic messaging via email and text (SMS) from my Linux servers.

== Required Packages ==

These packages are necessary for the all the following sections of this tutorial. In Debain, install them with <code>apt-get</code>:
<source lang="sh">
apt-get install ssmtp procmail fetchmail
</source>

== Directory Structure ==

Just for reference, here are the locations of the relevant files:
<source>
/
├── etc
│ └── ssmtp
│ └── ssmtp.conf
└── scripts
├── config
│ ├── accounts.conf
│ ├── ddns-fetchmailrc
│ └── ddns-mailprocess.sh
├── ddns.sh
├── email.sh
├── external-ip.sh
├── notifications.sh
└── sms.sh
</source>

And permissions:
<source lang="shell">
ls -l /scripts
</source>
<pre class="out">
drwxr-xr-x 4 root config 4096 Jun 20 08:52 config
-rwxr-xr-- 1 root root 260 Jun 20 08:40 ddns.sh
-rwxr-xr-- 1 root mailers 564 Apr 23 12:18 email.sh
-rwxr-xr-- 1 root root 529 Apr 27 07:56 external-ip.sh
-rwxr-xr-- 1 root root 3834 May 15 08:32 notifications.sh
-rwxr-xr-- 1 root texters 545 Apr 23 12:24 sms.sh
</pre>

<source lang="shell">
ls -l /scripts/config
</source>
<pre class="out">
-rwxr-x--- 1 root mailers 147 May 1 13:01 accounts.conf
-rwx------ 1 root root 246 May 21 09:49 ddns-fetchmailrc
-rwxr-x--- 1 root config 604 Jun 20 08:52 ddns-mailprocess.sh
</pre>

== Create Security Groups ==

I use group membership to control read access to certain files. You don't have to do this, but it was useful for me.

Create the groups:
<source lang="sh">
groupadd texters #allowed to sent text messages
groupadd mailers #allowed to send email messages
groupadd config #allowed to read other config files
</source>

You can add a user to all three groups like this:
<source lang="sh">
usermod -aG texters,mailers,config username
</source>

== Email and Text Messaging with SSMTP ==

First set up the <code>/etc/ssmtp/ssmtp.conf</code>. I use a dedicated Gmail account (named serveraccount@gmail.com in the example below) for all of my server messaging. When I receive an email from my server, it will look like it's coming from that Gmail.

Make a backup copy of the original config:
<source lang="sh">
cp /etc/ssmtp/ssmtp.conf /etc/ssmtp/ssmtp.conf.orig
</source>

Here are the contents of my modified <code>/etc/ssmtp/ssmtp.conf</code>. Replace the relevant values.
<source lang="sh">
#
# Config file for sSMTP sendmail
#
# The person who gets all mail for userids < 1000
# Make this empty to disable rewriting.
root=serveraccount

# The place where the mail goes. The actual machine name is required no
# MX records are consulted. Commonly mailhosts are named mail.domain.com
#mailhub=mail

# Where will the mail seem to come from?
rewriteDomain=gmail.com

# The full hostname
# This can be left as 'localhost'
hostname=localhost

# Are users allowed to set their own From: address?
# YES - Allow the user to specify their own From: address
# NO - Use the system generated From: address
FromLineOverride=YES

mailhub=smtp.gmail.com:587
UseStartTLS=YES
UseTLS=YES
AuthMethod=LOGIN
AuthUser=serveraccount@gmail.com
AuthPass=InsertPasswordHere
TLS_CA_File=/etc/pki/tls/certs/ca-bundle.crt
FromLineOverride=YES
</source>

Since the file contains a password, make sure the file is not readable to normal users.
<source lang="sh">
chown root:mail /etc/ssmtp/ssmtp.conf
chmod 640 /etc/ssmtp/ssmtp.conf
</source>

And because you don't have to remember this password, it would be a good idea to make it very long and complex (16+ characters; uppercase, lowercase, numbers, and special characters; no dictionary words).

You now need to log onto the serveraccount Gmail account and enable "less secure apps" at https://myaccount.google.com/lesssecureapps?pli=1 
[[File:Gmail-less-secure-app.png|frameless|600px]]

Here is more info about less secure apps: https://support.google.com/cloudidentity/answer/6260879?hl=en

You should now be able use the <code>ssmtp</code> command line tool from your server. Most of the time, you will need to include a subject line. It's important that it follows the format below (capital 'S' on Subject, colon, space, YourSubject, two newlines):
<source lang="sh">
echo -e "Subject: Hi\n\nHello, world!" | ssmtp myaccount@yahoo.com
</source>

== Create a Secure Accounts File ==

For some of the automatic messaging, you need to store text and email accounts in a file. To figure out the destination address to send text (SMS) messages to your cell, look on your cell provider's website for the proper account/domain name. It will probably be something like "<your-phone-number>@<provider-domain>". [https://kb.sandisk.com/app/answers/detail/a_id/17056/~/list-of-mobile-carrier-gateway-addresses List of provider addresses]

Contents of my <code>/scripts/config/accounts.conf</code> file:
<source lang="sh">
#!/bin/bash
#
# Secure account information
# Permissions must be 750 root:mailers

smsto="17775551234@myprovider.net"
mailto="myaccount@yahoo.com"
</source>

Change the permissions on the file:
<source lang="sh">
chown root:mailers /scripts/config/accounts.conf
chmod 750 /scripts/config/accounts.conf
</source>

== Email Script ==

This script can be used to send an email message.

Contents of the file <code>/scripts/email.sh</code>:
<source lang="shell">
#!/bin/bash

# Send email message:
# Usage: $0 "<Subject>" "<Message>"

default_subject="Alert from Server (`date`)"

subject=""
message=""

case $# in
2)
subject="$1"
message="$2"
;;
1)
subject="$default_subject"
message="$1"
;;
*)
echo "Send Email Message:"
echo " Usage: `basename $0` \"Message\""
echo " `basename $0` \"Subject\" \"Message\""
exit 1
;;
esac

dir="$(cd $(dirname ${BASH_SOURCE[0]})&&pwd)"
. $dir/config/accounts.conf

echo -e "Subject: $subject\n\n$message" | /usr/sbin/ssmtp $mailto
</source>

Set up permissions:
<source lang="sh">
chown root:mailers /scripts/email.sh
chmod 754 /scripts/email.sh
</source>

You can create an alias so you can quickly run this from the command line:
<source lang="sh">
echo "alias email='/scripts/email.sh'" >>~/.bashrc
source ~/.bashrc
</source>

Usage:
<source lang="sh">
# Send message with default subject
email "This is a test message."

# Send message with a subject
email "Test Subject" "This is a test message."
</source>

== Text Script ==

This script can be used to send a text (SMS) message.

Contents of the file <code>/scripts/sms.sh</code>:
<source lang="shell">
#!/bin/bash

# Send SMS message:
# Usage: $0 "<Subject>" "<Message>"

default_subject="Alert"

subject=""
message=""

case $# in
2)
subject="$1"
message="$2"
;;
1)
subject="$default_subject"
message="$1"
;;
*)
echo "Send SMS Message:"
echo " Usage: `basename $0` \"Message\""
echo " `basename $0` \"Subject\" \"Message\""
exit 1
;;
esac

dir="$(cd $(dirname ${BASH_SOURCE[0]})&&pwd)"
. $dir/config/accounts.conf

echo -e "To: $smsto\nSubject: $subject\n\n$message" | /usr/sbin/ssmtp $smsto
</source>

Set up permissions:
<source lang="sh">
chown root:texters /scripts/sms.sh
chmod 754 /scripts/sms.sh
</source>

You can create an alias so you can quickly run this from the command line:
<source lang="sh">
echo "alias sms='/scripts/sms.sh'" >>~/.bashrc
source ~/.bashrc
</source>

Usage:
<source lang="sh">
# Send message with default subject
sms "This is a test message."

# Send message with a subject
sms "Test Subject" "This is a test message."
</source>

== Scheduled Notifications Script ==

One of my life improvement tasks was to organize chores into scheduled chore days and rely on text/email notification to remind me to do them.

This dramatically reduced the amount of time I spend working on chores, and the amount of effort I spend thinking about what needs to be done. I could barely get projects done because every day I was loading my task list with chores. Now I don't think about chores until I'm notified. When I think of new chores, new items for my inventory, or other things I need to be reminded of, I update my checklists. When I feel I can improve scheduling or consolidate chores, I update my notifications script.

This utilizes the Email Script and Text Script from the previous sections.

Contents of the file <code>/scripts/notifications.sh</code>:
<source lang="shell">
#!/bin/bash
#
# Send regular notifications.
# Currently set to run daily at NOON.
#

# Get current datetime values
dt=(`date +%Y\ %m\ %d\ %H\ %M\ %S\ %a\ %s\ %I\ %p\ %Z`)
y=$((10#${dt[0]})) #year
M=$((10#${dt[1]})) #month
d=$((10#${dt[2]})) #day
h=$((10#${dt[3]})) #hour(24)
m=$((10#${dt[4]})) #minute
s=$((10#${dt[5]})) #second
w=${dt[6]} #day of week (eg. Sun)
e=$((10#${dt[7]})) #epoch
t=$((10#${dt[8]})) #hour(12)
p=${dt[9]} #meridian (AM/PM)
z=${dt[10]} #timezone (eg. PDT)

# Schedule command when date ($1) matched regex ($2) with extra grep parameters ($3)
# Use parameter -P at $3 for perl regex: in case you need to use (str1|str2).
# Example: schedule $M$d "(115|21)" -P && sms "Subject" "Message"
# Don't use -P when you want a range of numbers including 2 or more digit numbers (ie. [1-15]).
schedule(){ echo "$1" | grep -wq $3 "$2";}
sms(){ /scripts/sms.sh "$1" "$2";}
eml(){ /scripts/email.sh "$1" "$2";}
notify(){ sms "$1" "$2";eml "$1" "$2";}

# =================================
# ==== Temporary Notifications ====
# =================================

# Dentist appointment
#schedule $M$d "58" && notify "Dentist" "Appointment 4:00pm 10/31/2017"

# =================================
# ====== Chore Notifications ======
# =================================

# LAUNDRY DAY
# Day before
schedule $w$d "Mon[1-7]" && notify "LAUNDRY DAY" "WORK: Check gas. HOME: Do laundry, put laundry away."
schedule $w$d "Mon(15|16|17|18|19|20|21)" -P && notify "LAUNDRY DAY" "WORK: Check gas. HOME: Do laundry, put laundry away."

# WEEKLY CLEANING DAY
schedule $w "Tue" && notify "WEEKLY CLEANING DAY" "WORK: Fill gas, shopping. HOME: Clean, litter, sweep/vac, fridge, trash, check meds."
# Day after
schedule $w "Wed" && notify "WEEKLY REMINDER" "Order meds if necessary."

# MONTHLY CLEANING DAY
schedule $w$d "Tue[1-7]" && notify "MONTHLY CLEANING DAY" "WORK: Car stuff. HOME: Dishes, kitchen, bathroom, dust, inventory."

# BUSINESS DAY
schedule $d "[1-4]" && notify "BUSINESS DAY" "Rent due before 5th (\$720). Fedloan, budgeting, donations, next-buy."

# TECH DAY
schedule $w$d "Mon[1-7]" && notify "TECH DAY" "WORK: Updates, phone, healthcheck, security scan, organize files. HOME: Organize Workstation/Laptop, USB drives."

# SHOPPING DAY
schedule $w$d "Wed[1-7]" && notify "SHOPPING DAY" "Shopping, carwash. Maybe do during lunch."

# GROOMING DAY
schedule $w$d "Sun[1-7]" && notify "GROOMING DAY" "Shave/trim, clip nails."
schedule $w$d "Sun(15|16|17|18|19|20|21)" -P && notify "GROOMING DAY" "Shave/trim, clip nails."

# ELIMINATION DAY
schedule $w$d "Sun(15|16|17|18|19|20|21)" -P && notify "ELIMINATION DAY" "Do at least one item on TO_ELIMINATE list."

# INVENTORY DAY
# Disabled. Inventory is now included in monthly cleaning day.
# schedule $w$d "Tue[1-7]" && notify "INVENTORY DAY" "Do home, car, and office inventory."

# =================================
# = Other Permanent Notifications =
# =================================

# Air filter replacement notifications
schedule $M$d "71" && notify "Air Filter" "Holmes HAP726: Replace HEPA filters (model:HAPF600,qty:2)"
schedule $M$d "[1|7]1" && notify "Air Filter" "Holmes HAP726: Replace Carbon filters (model:HAPF600,qty:2)"
</source>

Now set the permissions:
<source lang="sh">
chown root:root /scripts/external-ip.sh
chmod 754 /scripts/external-ip.sh
</source>

== Reporting External IP Address ==

My home server does not have a static IP address, so I use dynamic DNS. With my free DDNS service, I have to renew the domain name every 30 days. So if I forget to renew it, it will expire and I won't be able to access my server unless I know the IP address. As a contingency, I created a script that sends my external IP address to an email account every 6 hours. Then at least I would be able find out what my last IP was and use that to access my server.

Contents of the file <code>/scripts/external-ip.sh</code>:
<source lang="shell">
#!/bin/bash

log="/var/log/external-ip.log"
ipsrc="http://checkip.dyndns.org"
date="`date`"
addr="myaccount@yahoo.com"

ip=`curl -s --connect-timeout 3 $ipsrc 2>/dev/null|grep -Po "Current IP Address: .*?\<"|tr '<' '\0'`
echo "IP: $ip"

if [ -z "$ip" ];then
echo "$date ERROR: Could not get external IP from $ipsrc" >>$log
else
echo -e "Subject:[`hostname`] $date $ip" | /usr/sbin/ssmtp $addr
if [ "$?" = "0" ];then
echo "$date SUCCESS: $ip sent to $addr" >>$log
else
echo "$date ERROR: Could not send to $addr" >>$log
fi
fi
</source>

Now set the permissions:
<source lang="sh">
chown root:root /scripts/external-ip.sh
chmod 754 /scripts/external-ip.sh
</source>

This script appends to a log file <code>/var/log/external-ip.log</code>:
<source lang="sh">
touch /var/log/external-ip.log
chown root:root /var/log/external-ip.log
chmod 644 /var/log/external-ip.log
</source>

== Automatic Email Download ==

As mentioned in a previous section, I use free dynamic DNS which requires that I renew it manually every 30 days. I need to remind myself to do this. My provider sends an email notification a few days before it expires, but I hate email and I don't want it in my face all the time, certainly not in my phone.

The best solution I found was to retrieve the email automatically and send me a text message with only the subject line in the message. I eventually created a second method of notification: it generates a file in a place that I regularly go, the folder that contains all of my to-do lists.

Contents of the file <code>/scripts/ddns.sh</code>:
<source lang="shell">
#!/bin/bash
#
# This script is run by a cron job.

/usr/bin/fetchmail -N -d0 -f "/scripts/config/ddns-fetchmailrc" -m "/scripts/config/ddns-mailprocess.sh"

alertfile="/shares/Private/000__DDNS-ALERT__.txt"
if [ -e $alertfile ];then
chown root:root $alertfile
chmod 777 $alertfile
fi
</source>

Contents of the file <code>/scripts/config/ddns-mailprocess.sh</code>:
<source lang="shell">
#!/bin/bash
#
# This script is run by /scripts/ddns.sh

mailto="17775551234@myprovider.net"
date="`date`"
log="/var/log/ddns.log"
alertfile="/shares/Private/000__DDNS-ALERT__.txt"
sms="/scripts/sms.sh"

cat /dev/stdin | grep -i "^Subject:" | sed 's/Subject\://g' | $sms "DDNS" "`cat /dev/stdin` ( $date )" &&\
echo "$date - DDNS notification sent to $mailto" | tee -a $log | sed "s/$mailto/cell\ phone/g" >$alertfile &&\
chmod 777 $alertfile
</source>

Contents of the file <code>/scripts/config/ddns-fetchmailrc</code>:
<source lang="shell">
#
# This rc file is run by /scripts/ddns.sh
# This file MUST have root:root and chmod 700

set postmaster "username";

poll "imap.mail.yahoo.com" protocol IMAP username "myaccount@yahoo.com" password "InsertPasswordHere" is "username" here keep folder "DDNS-Mailbox" ssl
</source>

You'll notice that it creates a file <code>/shares/Private/000__DDNS-ALERT__.txt</code>. The "000" is just to put it at the top of the directory listing. Also notice that I make it read-write for everyone so I can delete it from my webapp.

Set up permissions on all three files, and create the log file:
<source lang="sh">
touch /var/log/ddns.log
chown root:root /var/log/ddns.log
chmod 640 /var/log/ddns.log

chown root:root /scripts/ddns.sh
chmod 754 /scripts/ddns.sh

chown root:config /scripts/config/ddns-mailprocess.sh
chmod 750 /scripts/config/ddns-mailprocess.sh

chown root:root /scripts/config/ddns-fetchmailrc
chmod 700 /scripts/config/ddns-fetchmailrc
</source>

UPDATE February 2021: Yahoo now requires you to create a secure app password. See [[#yahoo-app-pass|this section]].

When you run <code>ddns.sh</code> as root it gives you a warning about running as root. This is okay.
<pre class="out">
fetchmail: WARNING: Running as root is discouraged.
</pre>

If permissions on <code>ddns-fetchmailrc</code> are not correct, you will get this failure message:
<pre class="out">
File /scripts/config/ddns-fetchmailrc must have no more than -rwx------ (0700) permissions.
</pre>

== Set Up Cron ==

Just for reference, here are the entries I made in my <code>/etc/crontab</code> file:
<source lang="sh">
# Crontabs to be run without 'run-parts'
#
# RUN AT NOON
0 12 * * * root /scripts/ddns.sh
0 12 * * * root /scripts/notifications.sh
# RUN EVERY 6 HOURS
1 0,6,12,18 * * * root /scripts/external-ip.sh
</source>

== Yahoo App Password ==

As of February 2021, Yahoo changed that way third party apps can access it. Instead of using your normal password, you need to generate an app password.

# Login to Yahoo, click you user icon, and click Account Info.
# Click Account Security.
# Click Manage app passwords.
# Click the Select your app drop-down and select Other app.
# Type a name for the app then click Generate.
# Now you can copy the password and use it in your app. Once you navigate away from this page, you will not be able to retrieve the password again. You will have to generate another password.

Automatic Email and Text Notifications

2021-02-26T14:10:21Z

Beard: /* Set Up Cron */

These tutorials describe my method of automatic messaging via email and text (SMS) from my Linux servers.

== Required Packages ==

These packages are necessary for the all the following sections of this tutorial. In Debain, install them with <code>apt-get</code>:
<source lang="sh">
apt-get install ssmtp procmail fetchmail
</source>

== Directory Structure ==

Just for reference, here are the locations of the relevant files:
<source>
/
├── etc
│ └── ssmtp
│ └── ssmtp.conf
└── scripts
├── config
│ ├── accounts.conf
│ ├── ddns-fetchmailrc
│ └── ddns-mailprocess.sh
├── ddns.sh
├── email.sh
├── external-ip.sh
├── notifications.sh
└── sms.sh
</source>

And permissions:
<source lang="shell">
ls -l /scripts
</source>
<pre class="out">
drwxr-xr-x 4 root config 4096 Jun 20 08:52 config
-rwxr-xr-- 1 root root 260 Jun 20 08:40 ddns.sh
-rwxr-xr-- 1 root mailers 564 Apr 23 12:18 email.sh
-rwxr-xr-- 1 root root 529 Apr 27 07:56 external-ip.sh
-rwxr-xr-- 1 root root 3834 May 15 08:32 notifications.sh
-rwxr-xr-- 1 root texters 545 Apr 23 12:24 sms.sh
</pre>

<source lang="shell">
ls -l /scripts/config
</source>
<pre class="out">
-rwxr-x--- 1 root mailers 147 May 1 13:01 accounts.conf
-rwx------ 1 root root 246 May 21 09:49 ddns-fetchmailrc
-rwxr-x--- 1 root config 604 Jun 20 08:52 ddns-mailprocess.sh
</pre>

== Create Security Groups ==

I use group membership to control read access to certain files. You don't have to do this, but it was useful for me.

Create the groups:
<source lang="sh">
groupadd texters #allowed to sent text messages
groupadd mailers #allowed to send email messages
groupadd config #allowed to read other config files
</source>

You can add a user to all three groups like this:
<source lang="sh">
usermod -aG texters,mailers,config username
</source>

== Email and Text Messaging with SSMTP ==

First set up the <code>/etc/ssmtp/ssmtp.conf</code>. I use a dedicated Gmail account (named serveraccount@gmail.com in the example below) for all of my server messaging. When I receive an email from my server, it will look like it's coming from that Gmail.

Make a backup copy of the original config:
<source lang="sh">
cp /etc/ssmtp/ssmtp.conf /etc/ssmtp/ssmtp.conf.orig
</source>

Here are the contents of my modified <code>/etc/ssmtp/ssmtp.conf</code>. Replace the relevant values.
<source lang="sh">
#
# Config file for sSMTP sendmail
#
# The person who gets all mail for userids < 1000
# Make this empty to disable rewriting.
root=serveraccount

# The place where the mail goes. The actual machine name is required no
# MX records are consulted. Commonly mailhosts are named mail.domain.com
#mailhub=mail

# Where will the mail seem to come from?
rewriteDomain=gmail.com

# The full hostname
# This can be left as 'localhost'
hostname=localhost

# Are users allowed to set their own From: address?
# YES - Allow the user to specify their own From: address
# NO - Use the system generated From: address
FromLineOverride=YES

mailhub=smtp.gmail.com:587
UseStartTLS=YES
UseTLS=YES
AuthMethod=LOGIN
AuthUser=serveraccount@gmail.com
AuthPass=InsertPasswordHere
TLS_CA_File=/etc/pki/tls/certs/ca-bundle.crt
FromLineOverride=YES
</source>

Since the file contains a password, make sure the file is not readable to normal users.
<source lang="sh">
chown root:mail /etc/ssmtp/ssmtp.conf
chmod 640 /etc/ssmtp/ssmtp.conf
</source>

And because you don't have to remember this password, it would be a good idea to make it very long and complex (16+ characters; uppercase, lowercase, numbers, and special characters; no dictionary words).

You now need to log onto the serveraccount Gmail account and enable "less secure apps" at https://myaccount.google.com/lesssecureapps?pli=1 
[[File:Gmail-less-secure-app.png|frameless|600px]]

Here is more info about less secure apps: https://support.google.com/cloudidentity/answer/6260879?hl=en

You should now be able use the <code>ssmtp</code> command line tool from your server. Most of the time, you will need to include a subject line. It's important that it follows the format below (capital 'S' on Subject, colon, space, YourSubject, two newlines):
<source lang="sh">
echo -e "Subject: Hi\n\nHello, world!" | ssmtp myaccount@yahoo.com
</source>

== Create a Secure Accounts File ==

For some of the automatic messaging, you need to store text and email accounts in a file. To figure out the destination address to send text (SMS) messages to your cell, look on your cell provider's website for the proper account/domain name. It will probably be something like "<your-phone-number>@<provider-domain>". [https://kb.sandisk.com/app/answers/detail/a_id/17056/~/list-of-mobile-carrier-gateway-addresses List of provider addresses]

Contents of my <code>/scripts/config/accounts.conf</code> file:
<source lang="sh">
#!/bin/bash
#
# Secure account information
# Permissions must be 750 root:mailers

smsto="17775551234@myprovider.net"
mailto="myaccount@yahoo.com"
</source>

Change the permissions on the file:
<source lang="sh">
chown root:mailers /scripts/config/accounts.conf
chmod 750 /scripts/config/accounts.conf
</source>

== Email Script ==

This script can be used to send an email message.

Contents of the file <code>/scripts/email.sh</code>:
<source lang="shell">
#!/bin/bash

# Send email message:
# Usage: $0 "<Subject>" "<Message>"

default_subject="Alert from Server (`date`)"

subject=""
message=""

case $# in
2)
subject="$1"
message="$2"
;;
1)
subject="$default_subject"
message="$1"
;;
*)
echo "Send Email Message:"
echo " Usage: `basename $0` \"Message\""
echo " `basename $0` \"Subject\" \"Message\""
exit 1
;;
esac

dir="$(cd $(dirname ${BASH_SOURCE[0]})&&pwd)"
. $dir/config/accounts.conf

echo -e "Subject: $subject\n\n$message" | /usr/sbin/ssmtp $mailto
</source>

Set up permissions:
<source lang="sh">
chown root:mailers /scripts/email.sh
chmod 754 /scripts/email.sh
</source>

You can create an alias so you can quickly run this from the command line:
<source lang="sh">
echo "alias email='/scripts/email.sh'" >>~/.bashrc
source ~/.bashrc
</source>

Usage:
<source lang="sh">
# Send message with default subject
email "This is a test message."

# Send message with a subject
email "Test Subject" "This is a test message."
</source>

== Text Script ==

This script can be used to send a text (SMS) message.

Contents of the file <code>/scripts/sms.sh</code>:
<source lang="shell">
#!/bin/bash

# Send SMS message:
# Usage: $0 "<Subject>" "<Message>"

default_subject="Alert"

subject=""
message=""

case $# in
2)
subject="$1"
message="$2"
;;
1)
subject="$default_subject"
message="$1"
;;
*)
echo "Send SMS Message:"
echo " Usage: `basename $0` \"Message\""
echo " `basename $0` \"Subject\" \"Message\""
exit 1
;;
esac

dir="$(cd $(dirname ${BASH_SOURCE[0]})&&pwd)"
. $dir/config/accounts.conf

echo -e "To: $smsto\nSubject: $subject\n\n$message" | /usr/sbin/ssmtp $smsto
</source>

Set up permissions:
<source lang="sh">
chown root:texters /scripts/sms.sh
chmod 754 /scripts/sms.sh
</source>

You can create an alias so you can quickly run this from the command line:
<source lang="sh">
echo "alias sms='/scripts/sms.sh'" >>~/.bashrc
source ~/.bashrc
</source>

Usage:
<source lang="sh">
# Send message with default subject
sms "This is a test message."

# Send message with a subject
sms "Test Subject" "This is a test message."
</source>

== Scheduled Notifications Script ==

One of my life improvement tasks was to organize chores into scheduled chore days and rely on text/email notification to remind me to do them.

This dramatically reduced the amount of time I spend working on chores, and the amount of effort I spend thinking about what needs to be done. I could barely get projects done because every day I was loading my task list with chores. Now I don't think about chores until I'm notified. When I think of new chores, new items for my inventory, or other things I need to be reminded of, I update my checklists. When I feel I can improve scheduling or consolidate chores, I update my notifications script.

This utilizes the Email Script and Text Script from the previous sections.

Contents of the file <code>/scripts/notifications.sh</code>:
<source lang="shell">
#!/bin/bash
#
# Send regular notifications.
# Currently set to run daily at NOON.
#

# Get current datetime values
dt=(`date +%Y\ %m\ %d\ %H\ %M\ %S\ %a\ %s\ %I\ %p\ %Z`)
y=$((10#${dt[0]})) #year
M=$((10#${dt[1]})) #month
d=$((10#${dt[2]})) #day
h=$((10#${dt[3]})) #hour(24)
m=$((10#${dt[4]})) #minute
s=$((10#${dt[5]})) #second
w=${dt[6]} #day of week (eg. Sun)
e=$((10#${dt[7]})) #epoch
t=$((10#${dt[8]})) #hour(12)
p=${dt[9]} #meridian (AM/PM)
z=${dt[10]} #timezone (eg. PDT)

# Schedule command when date ($1) matched regex ($2) with extra grep parameters ($3)
# Use parameter -P at $3 for perl regex: in case you need to use (str1|str2).
# Example: schedule $M$d "(115|21)" -P && sms "Subject" "Message"
# Don't use -P when you want a range of numbers including 2 or more digit numbers (ie. [1-15]).
schedule(){ echo "$1" | grep -wq $3 "$2";}
sms(){ /scripts/sms.sh "$1" "$2";}
eml(){ /scripts/email.sh "$1" "$2";}
notify(){ sms "$1" "$2";eml "$1" "$2";}

# =================================
# ==== Temporary Notifications ====
# =================================

# Dentist appointment
#schedule $M$d "58" && notify "Dentist" "Appointment 4:00pm 10/31/2017"

# =================================
# ====== Chore Notifications ======
# =================================

# LAUNDRY DAY
# Day before
schedule $w$d "Mon[1-7]" && notify "LAUNDRY DAY" "WORK: Check gas. HOME: Do laundry, put laundry away."
schedule $w$d "Mon(15|16|17|18|19|20|21)" -P && notify "LAUNDRY DAY" "WORK: Check gas. HOME: Do laundry, put laundry away."

# WEEKLY CLEANING DAY
schedule $w "Tue" && notify "WEEKLY CLEANING DAY" "WORK: Fill gas, shopping. HOME: Clean, litter, sweep/vac, fridge, trash, check meds."
# Day after
schedule $w "Wed" && notify "WEEKLY REMINDER" "Order meds if necessary."

# MONTHLY CLEANING DAY
schedule $w$d "Tue[1-7]" && notify "MONTHLY CLEANING DAY" "WORK: Car stuff. HOME: Dishes, kitchen, bathroom, dust, inventory."

# BUSINESS DAY
schedule $d "[1-4]" && notify "BUSINESS DAY" "Rent due before 5th (\$720). Fedloan, budgeting, donations, next-buy."

# TECH DAY
schedule $w$d "Mon[1-7]" && notify "TECH DAY" "WORK: Updates, phone, healthcheck, security scan, organize files. HOME: Organize Workstation/Laptop, USB drives."

# SHOPPING DAY
schedule $w$d "Wed[1-7]" && notify "SHOPPING DAY" "Shopping, carwash. Maybe do during lunch."

# GROOMING DAY
schedule $w$d "Sun[1-7]" && notify "GROOMING DAY" "Shave/trim, clip nails."
schedule $w$d "Sun(15|16|17|18|19|20|21)" -P && notify "GROOMING DAY" "Shave/trim, clip nails."

# ELIMINATION DAY
schedule $w$d "Sun(15|16|17|18|19|20|21)" -P && notify "ELIMINATION DAY" "Do at least one item on TO_ELIMINATE list."

# INVENTORY DAY
# Disabled. Inventory is now included in monthly cleaning day.
# schedule $w$d "Tue[1-7]" && notify "INVENTORY DAY" "Do home, car, and office inventory."

# =================================
# = Other Permanent Notifications =
# =================================

# Air filter replacement notifications
schedule $M$d "71" && notify "Air Filter" "Holmes HAP726: Replace HEPA filters (model:HAPF600,qty:2)"
schedule $M$d "[1|7]1" && notify "Air Filter" "Holmes HAP726: Replace Carbon filters (model:HAPF600,qty:2)"
</source>

Now set the permissions:
<source lang="sh">
chown root:root /scripts/external-ip.sh
chmod 754 /scripts/external-ip.sh
</source>

== Reporting External IP Address ==

My home server does not have a static IP address, so I use dynamic DNS. With my free DDNS service, I have to renew the domain name every 30 days. So if I forget to renew it, it will expire and I won't be able to access my server unless I know the IP address. As a contingency, I created a script that sends my external IP address to an email account every 6 hours. Then at least I would be able find out what my last IP was and use that to access my server.

Contents of the file <code>/scripts/external-ip.sh</code>:
<source lang="shell">
#!/bin/bash

log="/var/log/external-ip.log"
ipsrc="http://checkip.dyndns.org"
date="`date`"
addr="myaccount@yahoo.com"

ip=`curl -s --connect-timeout 3 $ipsrc 2>/dev/null|grep -Po "Current IP Address: .*?\<"|tr '<' '\0'`
echo "IP: $ip"

if [ -z "$ip" ];then
echo "$date ERROR: Could not get external IP from $ipsrc" >>$log
else
echo -e "Subject:[`hostname`] $date $ip" | /usr/sbin/ssmtp $addr
if [ "$?" = "0" ];then
echo "$date SUCCESS: $ip sent to $addr" >>$log
else
echo "$date ERROR: Could not send to $addr" >>$log
fi
fi
</source>

Now set the permissions:
<source lang="sh">
chown root:root /scripts/external-ip.sh
chmod 754 /scripts/external-ip.sh
</source>

This script appends to a log file <code>/var/log/external-ip.log</code>:
<source lang="sh">
touch /var/log/external-ip.log
chown root:root /var/log/external-ip.log
chmod 644 /var/log/external-ip.log
</source>

== Automatic Email Download ==

As mentioned in a previous section, I use free dynamic DNS which requires that I renew it manually every 30 days. I need to remind myself to do this. My provider sends an email notification a few days before it expires, but I hate email and I don't want it in my face all the time, certainly not in my phone.

The best solution I found was to retrieve the email automatically and send me a text message with only the subject line in the message. I eventually created a second method of notification: it generates a file in a place that I regularly go, the folder that contains all of my to-do lists.

Contents of the file <code>/scripts/ddns.sh</code>:
<source lang="shell">
#!/bin/bash
#
# This script is run by a cron job.

/usr/bin/fetchmail -N -d0 -f "/scripts/config/ddns-fetchmailrc" -m "/scripts/config/ddns-mailprocess.sh"

alertfile="/shares/Private/000__DDNS-ALERT__.txt"
if [ -e $alertfile ];then
chown root:root $alertfile
chmod 777 $alertfile
fi
</source>

Contents of the file <code>/scripts/config/ddns-mailprocess.sh</code>:
<source lang="shell">
#!/bin/bash
#
# This script is run by /scripts/ddns.sh

mailto="17775551234@myprovider.net"
date="`date`"
log="/var/log/ddns.log"
alertfile="/shares/Private/000__DDNS-ALERT__.txt"
sms="/scripts/sms.sh"

cat /dev/stdin | grep -i "^Subject:" | sed 's/Subject\://g' | $sms "DDNS" "`cat /dev/stdin` ( $date )" &&\
echo "$date - DDNS notification sent to $mailto" | tee -a $log | sed "s/$mailto/cell\ phone/g" >$alertfile &&\
chmod 777 $alertfile
</source>

Contents of the file <code>/scripts/config/ddns-fetchmailrc</code>:
<source lang="shell">
#
# This rc file is run by /scripts/ddns.sh
# This file MUST have root:root and chmod 700

set postmaster "username";

poll "imap.mail.yahoo.com" protocol IMAP username "myaccount@yahoo.com" password "InsertPasswordHere" is "username" here keep folder "DDNS-Mailbox" ssl
</source>

You'll notice that it creates a file <code>/shares/Private/000__DDNS-ALERT__.txt</code>. The "000" is just to put it at the top of the directory listing. Also notice that I make it read-write for everyone so I can delete it from my webapp.

Set up permissions on all three files, and create the log file:
<source lang="sh">
touch /var/log/ddns.log
chown root:root /var/log/ddns.log
chmod 640 /var/log/ddns.log

chown root:root /scripts/ddns.sh
chmod 754 /scripts/ddns.sh

chown root:config /scripts/config/ddns-mailprocess.sh
chmod 750 /scripts/config/ddns-mailprocess.sh

chown root:root /scripts/config/ddns-fetchmailrc
chmod 700 /scripts/config/ddns-fetchmailrc
</source>

UPDATE February 2021: Yahoo now requires you to create a secure app password. See [[#yahoo-app-pass|this section]].

When you run <code>ddns.sh</code> as root it gives you a warning about running as root. This is okay.
<pre class="out">
fetchmail: WARNING: Running as root is discouraged.
</pre>

If permissions on <code>ddns-fetchmailrc</code> are not correct, you will get this failure message:
<pre class="out">
File /scripts/config/ddns-fetchmailrc must have no more than -rwx------ (0700) permissions.
</pre>

== Set Up Cron ==

Just for reference, here are the entries I made in my <code>/etc/crontab</code> file:
<source lang="sh">
# Crontabs to be run without 'run-parts'
#
# RUN AT NOON
0 12 * * * root /scripts/ddns.sh
0 12 * * * root /scripts/notifications.sh
# RUN EVERY 6 HOURS
1 0,6,12,18 * * * root /scripts/external-ip.sh
</source>

== Yahoo App Password ==

As of February 2021, Yahoo changed that way third party apps can access it. Instead of using your normal password, you need to generate an app password.

# Login to Yahoo, click you user icon, and click Account Info.
# Click Account Security.
# Click Manage app passwords.
# Click the Select your app drop-down and select Other app.
# Type a name for the app then click Generate.
# Now you can copy the password and use it in your app. Once you navigate away from this page, you will not be able to retrieve the password again. You will have to generate another password.

Automatic Email and Text Notifications

2021-02-26T13:57:16Z

Beard: /* Automatic Email Download */

These tutorials describe my method of automatic messaging via email and text (SMS) from my Linux servers.

== Required Packages ==

These packages are necessary for the all the following sections of this tutorial. In Debain, install them with <code>apt-get</code>:
<source lang="sh">
apt-get install ssmtp procmail fetchmail
</source>

== Directory Structure ==

Just for reference, here are the locations of the relevant files:
<source>
/
├── etc
│ └── ssmtp
│ └── ssmtp.conf
└── scripts
├── config
│ ├── accounts.conf
│ ├── ddns-fetchmailrc
│ └── ddns-mailprocess.sh
├── ddns.sh
├── email.sh
├── external-ip.sh
├── notifications.sh
└── sms.sh
</source>

And permissions:
<source lang="shell">
ls -l /scripts
</source>
<pre class="out">
drwxr-xr-x 4 root config 4096 Jun 20 08:52 config
-rwxr-xr-- 1 root root 260 Jun 20 08:40 ddns.sh
-rwxr-xr-- 1 root mailers 564 Apr 23 12:18 email.sh
-rwxr-xr-- 1 root root 529 Apr 27 07:56 external-ip.sh
-rwxr-xr-- 1 root root 3834 May 15 08:32 notifications.sh
-rwxr-xr-- 1 root texters 545 Apr 23 12:24 sms.sh
</pre>

<source lang="shell">
ls -l /scripts/config
</source>
<pre class="out">
-rwxr-x--- 1 root mailers 147 May 1 13:01 accounts.conf
-rwx------ 1 root root 246 May 21 09:49 ddns-fetchmailrc
-rwxr-x--- 1 root config 604 Jun 20 08:52 ddns-mailprocess.sh
</pre>

== Create Security Groups ==

I use group membership to control read access to certain files. You don't have to do this, but it was useful for me.

Create the groups:
<source lang="sh">
groupadd texters #allowed to sent text messages
groupadd mailers #allowed to send email messages
groupadd config #allowed to read other config files
</source>

You can add a user to all three groups like this:
<source lang="sh">
usermod -aG texters,mailers,config username
</source>

== Email and Text Messaging with SSMTP ==

First set up the <code>/etc/ssmtp/ssmtp.conf</code>. I use a dedicated Gmail account (named serveraccount@gmail.com in the example below) for all of my server messaging. When I receive an email from my server, it will look like it's coming from that Gmail.

Make a backup copy of the original config:
<source lang="sh">
cp /etc/ssmtp/ssmtp.conf /etc/ssmtp/ssmtp.conf.orig
</source>

Here are the contents of my modified <code>/etc/ssmtp/ssmtp.conf</code>. Replace the relevant values.
<source lang="sh">
#
# Config file for sSMTP sendmail
#
# The person who gets all mail for userids < 1000
# Make this empty to disable rewriting.
root=serveraccount

# The place where the mail goes. The actual machine name is required no
# MX records are consulted. Commonly mailhosts are named mail.domain.com
#mailhub=mail

# Where will the mail seem to come from?
rewriteDomain=gmail.com

# The full hostname
# This can be left as 'localhost'
hostname=localhost

# Are users allowed to set their own From: address?
# YES - Allow the user to specify their own From: address
# NO - Use the system generated From: address
FromLineOverride=YES

mailhub=smtp.gmail.com:587
UseStartTLS=YES
UseTLS=YES
AuthMethod=LOGIN
AuthUser=serveraccount@gmail.com
AuthPass=InsertPasswordHere
TLS_CA_File=/etc/pki/tls/certs/ca-bundle.crt
FromLineOverride=YES
</source>

Since the file contains a password, make sure the file is not readable to normal users.
<source lang="sh">
chown root:mail /etc/ssmtp/ssmtp.conf
chmod 640 /etc/ssmtp/ssmtp.conf
</source>

And because you don't have to remember this password, it would be a good idea to make it very long and complex (16+ characters; uppercase, lowercase, numbers, and special characters; no dictionary words).

You now need to log onto the serveraccount Gmail account and enable "less secure apps" at https://myaccount.google.com/lesssecureapps?pli=1 
[[File:Gmail-less-secure-app.png|frameless|600px]]

Here is more info about less secure apps: https://support.google.com/cloudidentity/answer/6260879?hl=en

You should now be able use the <code>ssmtp</code> command line tool from your server. Most of the time, you will need to include a subject line. It's important that it follows the format below (capital 'S' on Subject, colon, space, YourSubject, two newlines):
<source lang="sh">
echo -e "Subject: Hi\n\nHello, world!" | ssmtp myaccount@yahoo.com
</source>

== Create a Secure Accounts File ==

For some of the automatic messaging, you need to store text and email accounts in a file. To figure out the destination address to send text (SMS) messages to your cell, look on your cell provider's website for the proper account/domain name. It will probably be something like "<your-phone-number>@<provider-domain>". [https://kb.sandisk.com/app/answers/detail/a_id/17056/~/list-of-mobile-carrier-gateway-addresses List of provider addresses]

Contents of my <code>/scripts/config/accounts.conf</code> file:
<source lang="sh">
#!/bin/bash
#
# Secure account information
# Permissions must be 750 root:mailers

smsto="17775551234@myprovider.net"
mailto="myaccount@yahoo.com"
</source>

Change the permissions on the file:
<source lang="sh">
chown root:mailers /scripts/config/accounts.conf
chmod 750 /scripts/config/accounts.conf
</source>

== Email Script ==

This script can be used to send an email message.

Contents of the file <code>/scripts/email.sh</code>:
<source lang="shell">
#!/bin/bash

# Send email message:
# Usage: $0 "<Subject>" "<Message>"

default_subject="Alert from Server (`date`)"

subject=""
message=""

case $# in
2)
subject="$1"
message="$2"
;;
1)
subject="$default_subject"
message="$1"
;;
*)
echo "Send Email Message:"
echo " Usage: `basename $0` \"Message\""
echo " `basename $0` \"Subject\" \"Message\""
exit 1
;;
esac

dir="$(cd $(dirname ${BASH_SOURCE[0]})&&pwd)"
. $dir/config/accounts.conf

echo -e "Subject: $subject\n\n$message" | /usr/sbin/ssmtp $mailto
</source>

Set up permissions:
<source lang="sh">
chown root:mailers /scripts/email.sh
chmod 754 /scripts/email.sh
</source>

You can create an alias so you can quickly run this from the command line:
<source lang="sh">
echo "alias email='/scripts/email.sh'" >>~/.bashrc
source ~/.bashrc
</source>

Usage:
<source lang="sh">
# Send message with default subject
email "This is a test message."

# Send message with a subject
email "Test Subject" "This is a test message."
</source>

== Text Script ==

This script can be used to send a text (SMS) message.

Contents of the file <code>/scripts/sms.sh</code>:
<source lang="shell">
#!/bin/bash

# Send SMS message:
# Usage: $0 "<Subject>" "<Message>"

default_subject="Alert"

subject=""
message=""

case $# in
2)
subject="$1"
message="$2"
;;
1)
subject="$default_subject"
message="$1"
;;
*)
echo "Send SMS Message:"
echo " Usage: `basename $0` \"Message\""
echo " `basename $0` \"Subject\" \"Message\""
exit 1
;;
esac

dir="$(cd $(dirname ${BASH_SOURCE[0]})&&pwd)"
. $dir/config/accounts.conf

echo -e "To: $smsto\nSubject: $subject\n\n$message" | /usr/sbin/ssmtp $smsto
</source>

Set up permissions:
<source lang="sh">
chown root:texters /scripts/sms.sh
chmod 754 /scripts/sms.sh
</source>

You can create an alias so you can quickly run this from the command line:
<source lang="sh">
echo "alias sms='/scripts/sms.sh'" >>~/.bashrc
source ~/.bashrc
</source>

Usage:
<source lang="sh">
# Send message with default subject
sms "This is a test message."

# Send message with a subject
sms "Test Subject" "This is a test message."
</source>

== Scheduled Notifications Script ==

One of my life improvement tasks was to organize chores into scheduled chore days and rely on text/email notification to remind me to do them.

This dramatically reduced the amount of time I spend working on chores, and the amount of effort I spend thinking about what needs to be done. I could barely get projects done because every day I was loading my task list with chores. Now I don't think about chores until I'm notified. When I think of new chores, new items for my inventory, or other things I need to be reminded of, I update my checklists. When I feel I can improve scheduling or consolidate chores, I update my notifications script.

This utilizes the Email Script and Text Script from the previous sections.

Contents of the file <code>/scripts/notifications.sh</code>:
<source lang="shell">
#!/bin/bash
#
# Send regular notifications.
# Currently set to run daily at NOON.
#

# Get current datetime values
dt=(`date +%Y\ %m\ %d\ %H\ %M\ %S\ %a\ %s\ %I\ %p\ %Z`)
y=$((10#${dt[0]})) #year
M=$((10#${dt[1]})) #month
d=$((10#${dt[2]})) #day
h=$((10#${dt[3]})) #hour(24)
m=$((10#${dt[4]})) #minute
s=$((10#${dt[5]})) #second
w=${dt[6]} #day of week (eg. Sun)
e=$((10#${dt[7]})) #epoch
t=$((10#${dt[8]})) #hour(12)
p=${dt[9]} #meridian (AM/PM)
z=${dt[10]} #timezone (eg. PDT)

# Schedule command when date ($1) matched regex ($2) with extra grep parameters ($3)
# Use parameter -P at $3 for perl regex: in case you need to use (str1|str2).
# Example: schedule $M$d "(115|21)" -P && sms "Subject" "Message"
# Don't use -P when you want a range of numbers including 2 or more digit numbers (ie. [1-15]).
schedule(){ echo "$1" | grep -wq $3 "$2";}
sms(){ /scripts/sms.sh "$1" "$2";}
eml(){ /scripts/email.sh "$1" "$2";}
notify(){ sms "$1" "$2";eml "$1" "$2";}

# =================================
# ==== Temporary Notifications ====
# =================================

# Dentist appointment
#schedule $M$d "58" && notify "Dentist" "Appointment 4:00pm 10/31/2017"

# =================================
# ====== Chore Notifications ======
# =================================

# LAUNDRY DAY
# Day before
schedule $w$d "Mon[1-7]" && notify "LAUNDRY DAY" "WORK: Check gas. HOME: Do laundry, put laundry away."
schedule $w$d "Mon(15|16|17|18|19|20|21)" -P && notify "LAUNDRY DAY" "WORK: Check gas. HOME: Do laundry, put laundry away."

# WEEKLY CLEANING DAY
schedule $w "Tue" && notify "WEEKLY CLEANING DAY" "WORK: Fill gas, shopping. HOME: Clean, litter, sweep/vac, fridge, trash, check meds."
# Day after
schedule $w "Wed" && notify "WEEKLY REMINDER" "Order meds if necessary."

# MONTHLY CLEANING DAY
schedule $w$d "Tue[1-7]" && notify "MONTHLY CLEANING DAY" "WORK: Car stuff. HOME: Dishes, kitchen, bathroom, dust, inventory."

# BUSINESS DAY
schedule $d "[1-4]" && notify "BUSINESS DAY" "Rent due before 5th (\$720). Fedloan, budgeting, donations, next-buy."

# TECH DAY
schedule $w$d "Mon[1-7]" && notify "TECH DAY" "WORK: Updates, phone, healthcheck, security scan, organize files. HOME: Organize Workstation/Laptop, USB drives."

# SHOPPING DAY
schedule $w$d "Wed[1-7]" && notify "SHOPPING DAY" "Shopping, carwash. Maybe do during lunch."

# GROOMING DAY
schedule $w$d "Sun[1-7]" && notify "GROOMING DAY" "Shave/trim, clip nails."
schedule $w$d "Sun(15|16|17|18|19|20|21)" -P && notify "GROOMING DAY" "Shave/trim, clip nails."

# ELIMINATION DAY
schedule $w$d "Sun(15|16|17|18|19|20|21)" -P && notify "ELIMINATION DAY" "Do at least one item on TO_ELIMINATE list."

# INVENTORY DAY
# Disabled. Inventory is now included in monthly cleaning day.
# schedule $w$d "Tue[1-7]" && notify "INVENTORY DAY" "Do home, car, and office inventory."

# =================================
# = Other Permanent Notifications =
# =================================

# Air filter replacement notifications
schedule $M$d "71" && notify "Air Filter" "Holmes HAP726: Replace HEPA filters (model:HAPF600,qty:2)"
schedule $M$d "[1|7]1" && notify "Air Filter" "Holmes HAP726: Replace Carbon filters (model:HAPF600,qty:2)"
</source>

Now set the permissions:
<source lang="sh">
chown root:root /scripts/external-ip.sh
chmod 754 /scripts/external-ip.sh
</source>

== Reporting External IP Address ==

My home server does not have a static IP address, so I use dynamic DNS. With my free DDNS service, I have to renew the domain name every 30 days. So if I forget to renew it, it will expire and I won't be able to access my server unless I know the IP address. As a contingency, I created a script that sends my external IP address to an email account every 6 hours. Then at least I would be able find out what my last IP was and use that to access my server.

Contents of the file <code>/scripts/external-ip.sh</code>:
<source lang="shell">
#!/bin/bash

log="/var/log/external-ip.log"
ipsrc="http://checkip.dyndns.org"
date="`date`"
addr="myaccount@yahoo.com"

ip=`curl -s --connect-timeout 3 $ipsrc 2>/dev/null|grep -Po "Current IP Address: .*?\<"|tr '<' '\0'`
echo "IP: $ip"

if [ -z "$ip" ];then
echo "$date ERROR: Could not get external IP from $ipsrc" >>$log
else
echo -e "Subject:[`hostname`] $date $ip" | /usr/sbin/ssmtp $addr
if [ "$?" = "0" ];then
echo "$date SUCCESS: $ip sent to $addr" >>$log
else
echo "$date ERROR: Could not send to $addr" >>$log
fi
fi
</source>

Now set the permissions:
<source lang="sh">
chown root:root /scripts/external-ip.sh
chmod 754 /scripts/external-ip.sh
</source>

This script appends to a log file <code>/var/log/external-ip.log</code>:
<source lang="sh">
touch /var/log/external-ip.log
chown root:root /var/log/external-ip.log
chmod 644 /var/log/external-ip.log
</source>

== Automatic Email Download ==

As mentioned in a previous section, I use free dynamic DNS which requires that I renew it manually every 30 days. I need to remind myself to do this. My provider sends an email notification a few days before it expires, but I hate email and I don't want it in my face all the time, certainly not in my phone.

The best solution I found was to retrieve the email automatically and send me a text message with only the subject line in the message. I eventually created a second method of notification: it generates a file in a place that I regularly go, the folder that contains all of my to-do lists.

Contents of the file <code>/scripts/ddns.sh</code>:
<source lang="shell">
#!/bin/bash
#
# This script is run by a cron job.

/usr/bin/fetchmail -N -d0 -f "/scripts/config/ddns-fetchmailrc" -m "/scripts/config/ddns-mailprocess.sh"

alertfile="/shares/Private/000__DDNS-ALERT__.txt"
if [ -e $alertfile ];then
chown root:root $alertfile
chmod 777 $alertfile
fi
</source>

Contents of the file <code>/scripts/config/ddns-mailprocess.sh</code>:
<source lang="shell">
#!/bin/bash
#
# This script is run by /scripts/ddns.sh

mailto="17775551234@myprovider.net"
date="`date`"
log="/var/log/ddns.log"
alertfile="/shares/Private/000__DDNS-ALERT__.txt"
sms="/scripts/sms.sh"

cat /dev/stdin | grep -i "^Subject:" | sed 's/Subject\://g' | $sms "DDNS" "`cat /dev/stdin` ( $date )" &&\
echo "$date - DDNS notification sent to $mailto" | tee -a $log | sed "s/$mailto/cell\ phone/g" >$alertfile &&\
chmod 777 $alertfile
</source>

Contents of the file <code>/scripts/config/ddns-fetchmailrc</code>:
<source lang="shell">
#
# This rc file is run by /scripts/ddns.sh
# This file MUST have root:root and chmod 700

set postmaster "username";

poll "imap.mail.yahoo.com" protocol IMAP username "myaccount@yahoo.com" password "InsertPasswordHere" is "username" here keep folder "DDNS-Mailbox" ssl
</source>

You'll notice that it creates a file <code>/shares/Private/000__DDNS-ALERT__.txt</code>. The "000" is just to put it at the top of the directory listing. Also notice that I make it read-write for everyone so I can delete it from my webapp.

Set up permissions on all three files, and create the log file:
<source lang="sh">
touch /var/log/ddns.log
chown root:root /var/log/ddns.log
chmod 640 /var/log/ddns.log

chown root:root /scripts/ddns.sh
chmod 754 /scripts/ddns.sh

chown root:config /scripts/config/ddns-mailprocess.sh
chmod 750 /scripts/config/ddns-mailprocess.sh

chown root:root /scripts/config/ddns-fetchmailrc
chmod 700 /scripts/config/ddns-fetchmailrc
</source>

UPDATE February 2021: Yahoo now requires you to create a secure app password. See [[#yahoo-app-pass|this section]].

When you run <code>ddns.sh</code> as root it gives you a warning about running as root. This is okay.
<pre class="out">
fetchmail: WARNING: Running as root is discouraged.
</pre>

If permissions on <code>ddns-fetchmailrc</code> are not correct, you will get this failure message:
<pre class="out">
File /scripts/config/ddns-fetchmailrc must have no more than -rwx------ (0700) permissions.
</pre>

== Set Up Cron ==

Just for reference, here are the entries I made in my <code>/etc/crontab</code> file:
<source lang="sh">
# Crontabs to be run without 'run-parts'
#
# RUN AT NOON
0 12 * * * root /scripts/ddns.sh
0 12 * * * root /scripts/notifications.sh
# RUN EVERY 6 HOURS
1 0,6,12,18 * * * root /scripts/external-ip.sh
</source>

Dmesg Real Dates/TImestamps

2021-01-21T05:48:27Z

Beard:

Dmesg shows timestamps in seconds since the last boot, and newer versions of dmesg take the "-T" parameter like <code>dmesg -T</code> to display dates in human readable format, but in case your server is running an old version here's a great bash function that provides that functionality. I didn't write this I stole it from someone else. Keep in mind that if the system has been put to sleep, suspended, or hibernated then the timestamps will be inaccurate.

<source lang="sh">
dmesg_with_human_timestamps () {
$(type -P dmesg) "$@" | perl -w -e 'use strict;
my ($uptime) = do { local @ARGV="/proc/uptime";<>}; ($uptime) = ($uptime =~ /^(\d+)\./);
foreach my $line (<>) {
printf( ($line=~/^\[\s*(\d+)\.\d+\](.+)/) ? ( "[%s]%s\n", scalar localtime(time - $uptime + $1), $2 ) : $line )
}'
}
alias dmesg=dmesg_with_human_timestamps
</source>

Dmesg Real Dates/TImestamps

2021-01-21T05:46:57Z

Beard: Created page with "Dmesg shows timestamps in seconds since the last boot, and newer versions of dmesg take the "-T" parameter like <code>dmesg -T</code> to display dates in human readable format..."

Dmesg shows timestamps in seconds since the last boot, and newer versions of dmesg take the "-T" parameter like <code>dmesg -T</code> to display dates in human readable format, but in case your server is running an old version, here's a great bash function that I stole from someone else. Keep in mind that if the system has been put to sleep, suspended, or hibernated then the timestamps will be inaccurate.

<source lang="sh">
dmesg_with_human_timestamps () {
$(type -P dmesg) "$@" | perl -w -e 'use strict;
my ($uptime) = do { local @ARGV="/proc/uptime";<>}; ($uptime) = ($uptime =~ /^(\d+)\./);
foreach my $line (<>) {
printf( ($line=~/^\[\s*(\d+)\.\d+\](.+)/) ? ( "[%s]%s\n", scalar localtime(time - $uptime + $1), $2 ) : $line )
}'
}
alias dmesg=dmesg_with_human_timestamps
</source>

Linux

2021-01-21T05:37:30Z

Beard: /* Particular Problems/Solutions */

__TOC__

== General Linux Notes ==

* Massive list of [[Linux Commands]].
* Other notes about software, services, configs, etc. go to [[Notes]] page.

== Scripts ==

* [[Custom Window Snap]]: Gosnap (Good Old Snap) emulates the Aero Snap feature in Windows 7

== Custom Distros ==

* [[Custom Slax Bootable OS]]

== Tips and Tricks ==

* [[The Fastest Checksum]]
* [[List DHCP Leases]]
* [[Power Saving]]
* [[Disable Update Notifier]]
* [[Mouse/Touchpad Drivers and Settings]]
* [[Automatic Email and Text Notifications]]
* [[Raspberry Pi SSH Without Logging In]]
* [[Bash CSV Handling]]
* [[Bi-Directional Directory Synchronization]]
* [[Better Bash Configs]]

== Applications ==

* [[rdiff-backup]]: Incremental backup tool.
* [[Openssl - Generate Self-signed Certificate for Chrome]]
* [[Truecrypt Over NFS or SSH]]
* [[Vim]]
* [[Raspberry Pi Video Streaming]]

== Particular Problems/Solutions ==

* [[Kernel Panic: VFS :Unable to mount root fs on unknown-block]]
* [[The Problem with Journaling File systems on an SD Card]]
* [[Beyond The Max Audio Volume]]
* [[Unattended-Upgrades Automatically Rebooting The System]]
* [[Set Font Size on TTY]]
* [[Weird Characters in Terminal]]
* [[SSH Won't Work Via Shell Command in PHP]]
* [[Retrieve Package List from Dead System]]
* [[Ubuntu 18.04 Ctrl+Scroll Won't Zoom in Chromium]]
* [[Ubuntu 18.04 Audacity Poor Recording and Popping]]
* [[Systemd Private Tmp Folders]]
* [[Dmesg Real Dates/TImestamps]]

External Links

2020-12-03T17:15:08Z

Beard: /* Programming */

== Security Tools ==

* https://www.virustotal.com/: Multi-scanner anti-virus (no installation required).

== Programming ==

* https://fiddles.io/: Online boilerplates for all languages.
* http://cpp.sh/: Better online boilerplate for C++.
* https://regex101.com/: Online boilerplate for regular expressions.
* https://www.hex-rays.com/products/ida/support/download_freeware.shtml: Binary disassembler.
* https://www.epochconverter.com/: Unix Epoch Datetime Converter

== Web Development ==

=== CSS and Other Style Stuff ===

* http://paletton.com/: Color palette creator.
* http://www.colorzilla.com/gradient-editor/: CSS gradient generator
* http://www.cssmatic.com/: CSS Tools: gradient, border radius, texture, box shadow
* http://css3generator.com/: CSS multi-generator
* http://www.cssbuttongenerator.com/: CSS button generator
* https://www.hscripts.com/tools/drop-down-menu/index.php: JS drop-down menu generator
* http://purecssmenu.com/: CSS menu generator
* http://www.sassmeister.com/gist/5bcb7fefa9d05955f66c: Sass Lab
* https://beautifier.io/: Javescript, CSS, and HTML Unminifier/Beautifier (Code Expander)

=== Fonts ===

* https://fonts.google.com/: Google's fonts
* https://icomoon.io/: Font maker

=== Basic Tools and Info ===

* http://validator.w3.org/unicorn/: HTML validation tool
* https://www.xml-sitemaps.com/: XML sitemap generator
* https://www.browserstack.com/: Browser emulator
* http://www.ssec.edu/~tomw/java/unicode.html: Unicode List
* http://www.freeformatter.com/html-entities.html: Complete list of HTML entities

== Volunteer Computing ==

* https://boinc.berkeley.edu/: Berkeley distributed computing network (multiple projects).
* https://boinc.bakerlab.org/: Rosetta@Home protein folding.
* https://foldingathome.org/: Folding@Home protein folding.
* https://einsteinathome.org/: Einstein@Home physics simulation.
* https://lhcathome.cern.ch/lhcathome/: LHC@Home Large Hadron Collider simulation.
* https://eternagame.org/: A game that contributes to protein simulation as you play.
* https://www.zooniverse.org/: A lot of projects that allow people to actively participate in science.
* https://www.zooniverse.org/projects/zookeeper/galaxy-zoo: Help classify galaxies by examining telescope photos.
* https://www.zooniverse.org/projects/ianc2/exoplanet-explorers/: Help identify exoplanets.

== News and Information ==

* http://darksky.net/: Really nice weather report
* http://www.weathertab.com/: Long range weather forecast (1 year)
* http://www.ustream.tv/nasahdtv: NASA live stream
* http://everytimezone.com/: Visual chart of timezones
* http://www.spacerogue.net: Hacker/tech news
* http://www.freeinfosociety.com: Tons of free information

== Educational ==

* http://interactmath.com/: Free interactive math tutorials
* http://www.ptable.com/: Interactive periodic table
* http://ascendmath.com/fcm/html5/: Simple math flash cards
* https://www.desmos.com/calculator: Graphing calculator
* https://www.khanacademy.org: Free online academy (math, physics, chemistry, etc.)
* http://galaxyzoo.org: Volunteer to categorize galaxies
* http://www.planethunters.org: Volunteer to help identify exoplanets
* https://op-webtools.web.cern.ch/vistar/vistars.php: Large Hadron Collider monitor (LHC)
* http://ispy-webgl.web.cern.ch/ispy-webgl/: CMS Data Visualization
* https://www.aviso.altimetry.fr/en/data.html: Oceanic and Altimetric database

== Tutorials ==

=== Guacamole VNC Server ===

* http://guac-dev.org/doc/gug/
* https://gist.github.com/jeffersonmartin/8236574: Version 0.8.3 for Ubuntu Server
* http://www.linuxintro.org/wiki/Guacamole
* https://deviantengineer.com/2013/10/guacamole/

=== Ampache Streaming Media Server ===

* https://github.com/ampache/ampache/wiki/Installation

== Files and Software ==

* https://archive.org/: THE INTERNET ARCHIVE
* https://librivox.org/: Free audio books
* http://www.freeimages.com: Royalty-free/creative common images
* http://www.freewebtemplates.com/: Free web templates
* https://www.softaculous.com/apps/: Nice list of software
* https://www.draw.io/: Free web-based network diagram/flowchart designer (like Visio).
* http://www.emachineshop.com/machine-shop/Free-CAD-Design-Software/page100.html: Freee CAD software (also good for making gears).
* https://easyeda.com: Free circuit diagram software online
* https://www.circuitlab.com/editor/: Very simple free circuit diagram software online (can't save to file)
* ftp://ftp.ncbi.nih.gov/genomes/: National Institute of Health genome archives
* http://redobackup.org/: Bootable backup utility.
* https://www.sites.google.com/site/unoardusim/services: Arduino Uno simulator.

=== Service Manuals ===

* https://freeservicemanuals.info

== Hardware ==

* https://thepihut.com/: Raspberry Pi stuff
* https://www.newark.com/?COM=element14_store_Home: Electronics
* https://www.adafruit.com/: Electronics

== Materials ==

* http://www.tapplastics.com/: Custom plastics

== Art Tools ==

* http://www.text-image.com/convert/ascii.html: Image to ASCII art converter
* http://www.wordle.net/: word-cloud generator
* http://www.patorjk.com/software/taag/: text to ASCII art generator
* http://www.flamingtext.com/: Logo designer

== Audio Tools ==

* http://imtranslator.net/translation/text-to-speech/: text to speech

== Document Tools ==

* http://www.free-ocr.com/: Optical Character Recognition (OCR); finds text in an image
* http://www.myfonts.com/WhatTheFont/: Font identifier

== Space and Earth ==

* https://www.jasondavies.com/maps/transition/: interactive world map projections.
* https://worldview.earthdata.nasa.gov/: NASA Worldview.
* https://sdo.gsfc.nasa.gov/data/: NASA Solar Dynamics Observatory (SDO).
* https://helioviewer.org/: Interactive up-to-date view of the Sun.
* http://lmsal.com/isolsearch: Another interactive map of the Sun and solar activity.
* https://www.jwst.nasa.gov/webcam.html: Goddard Space Center clean-room webcams.
* https://science.ksc.nasa.gov/shuttle/countdown/video/: Kennedy Space Center webcams.
* http://www.isstracker.com/embed: International Space Station Tracker.
* https://spotthestation.nasa.gov/widget/: Spot The Station widget.
* http://www.ustream.tv/embed/6540154?html5ui: NASA Public-Education channel.
* http://www.ustream.tv/embed/10414700?html5ui: NASA TV Media.
* http://www.ustream.tv/embed/17074538?v=3&wmode=direct;autoplay=1: ISS Livestream 1
* http://www.ustream.tv/embed/9408562?v=3&wmode=direct;autoplay=1: ISS Livestream 2

== Privacy and Anti-Advertising ==

Scam Alerts
* https://www.consumer.ftc.gov/scam-alerts

Government Sites About Spam, Fraud, etc.
* https://attorneygeneral.nd.gov/consumer-resources/identity-theft/preventing-identity-theft
* https://www.consumer.ftc.gov/articles/0038-spam

Opt-Out Registries
* https://www.donotcall.gov/
* https://www.optoutprescreen.com
* https://dmachoice.thedma.org/
* http://www.directmail.com/mail_preference/

Privacy/Ad-blocker Tools
* https://ublock.org/: Browser plugin
* https://adblockplus.org/: Browser plugin
* https://pi-hole.net/: Network level ad-blocker (DNS-based)
* https://freek.ws/public-pi-hole/: Public hosted PiHole DNS Servers

VPN Services:
* https://www.expressvpn.com/: This company has the highest merits by my reckoning. Authorities have asked for logs and they were unable to provide it, which demonstrates that they are honest about their no-log policy. Off-shore jurisdiction: British Virgin Islands. Also, they have less usage restrictions than other VPN providers.

== Other Nifty Stuff ==

* https://www.herox.com/: A website where companies put bounties on innovation
* https://maroslaw.github.io/rainyday.js/demo012_1.html: Rainy window animation (press F11 to full-screen).
* http://www.beepbox.co/: 8-bit music synthesizer.
* http://www.eviloverlord.com/lists/overlord.html: A funny list of axioms for being a successful evil overlord.
* http://www.petittube.com/: Automatically plays random YouTube videos that have zero views, so you are literally the first viewer.
* http://www.virtualcolossus.co.uk/: Functional simulation of a Colossus Mk II.
* https://ban.ai/multics/: Virtual Multics Operating System
* http://asciicker.com/x13/: Incredible 3D ASCII based game (the "x13" is the version, use lower numbers to see older versions)
* https://ideasai.net/: An business idea generator powered by artificial intelligence (GPT-3)

External Links

2020-10-22T02:44:36Z

Beard: /* Other Nifty Stuff */

== Security Tools ==

* https://www.virustotal.com/: Multi-scanner anti-virus (no installation required).

== Programming ==

* https://fiddles.io/: Online boiler plates for all languages.
* http://cpp.sh/ : Better online boiler plate for C++.
* https://www.hex-rays.com/products/ida/support/download_freeware.shtml: Binary disassembler.
* https://www.epochconverter.com/: Unix Epoch Datetime Converter

== Web Development ==

=== CSS and Other Style Stuff ===

* http://paletton.com/: Color palette creator.
* http://www.colorzilla.com/gradient-editor/: CSS gradient generator
* http://www.cssmatic.com/: CSS Tools: gradient, border radius, texture, box shadow
* http://css3generator.com/: CSS multi-generator
* http://www.cssbuttongenerator.com/: CSS button generator
* https://www.hscripts.com/tools/drop-down-menu/index.php: JS drop-down menu generator
* http://purecssmenu.com/: CSS menu generator
* http://www.sassmeister.com/gist/5bcb7fefa9d05955f66c: Sass Lab
* https://beautifier.io/: Javescript, CSS, and HTML Unminifier/Beautifier (Code Expander)

=== Fonts ===

* https://fonts.google.com/: Google's fonts
* https://icomoon.io/: Font maker

=== Basic Tools and Info ===

* http://validator.w3.org/unicorn/: HTML validation tool
* https://www.xml-sitemaps.com/: XML sitemap generator
* https://www.browserstack.com/: Browser emulator
* http://www.ssec.edu/~tomw/java/unicode.html: Unicode List
* http://www.freeformatter.com/html-entities.html: Complete list of HTML entities

== Volunteer Computing ==

* https://boinc.berkeley.edu/: Berkeley distributed computing network (multiple projects).
* https://boinc.bakerlab.org/: Rosetta@Home protein folding.
* https://foldingathome.org/: Folding@Home protein folding.
* https://einsteinathome.org/: Einstein@Home physics simulation.
* https://lhcathome.cern.ch/lhcathome/: LHC@Home Large Hadron Collider simulation.
* https://eternagame.org/: A game that contributes to protein simulation as you play.
* https://www.zooniverse.org/: A lot of projects that allow people to actively participate in science.
* https://www.zooniverse.org/projects/zookeeper/galaxy-zoo: Help classify galaxies by examining telescope photos.
* https://www.zooniverse.org/projects/ianc2/exoplanet-explorers/: Help identify exoplanets.

== News and Information ==

* http://darksky.net/: Really nice weather report
* http://www.weathertab.com/: Long range weather forecast (1 year)
* http://www.ustream.tv/nasahdtv: NASA live stream
* http://everytimezone.com/: Visual chart of timezones
* http://www.spacerogue.net: Hacker/tech news
* http://www.freeinfosociety.com: Tons of free information

== Educational ==

* http://interactmath.com/: Free interactive math tutorials
* http://www.ptable.com/: Interactive periodic table
* http://ascendmath.com/fcm/html5/: Simple math flash cards
* https://www.desmos.com/calculator: Graphing calculator
* https://www.khanacademy.org: Free online academy (math, physics, chemistry, etc.)
* http://galaxyzoo.org: Volunteer to categorize galaxies
* http://www.planethunters.org: Volunteer to help identify exoplanets
* https://op-webtools.web.cern.ch/vistar/vistars.php: Large Hadron Collider monitor (LHC)
* http://ispy-webgl.web.cern.ch/ispy-webgl/: CMS Data Visualization
* https://www.aviso.altimetry.fr/en/data.html: Oceanic and Altimetric database

== Tutorials ==

=== Guacamole VNC Server ===

* http://guac-dev.org/doc/gug/
* https://gist.github.com/jeffersonmartin/8236574: Version 0.8.3 for Ubuntu Server
* http://www.linuxintro.org/wiki/Guacamole
* https://deviantengineer.com/2013/10/guacamole/

=== Ampache Streaming Media Server ===

* https://github.com/ampache/ampache/wiki/Installation

== Files and Software ==

* https://archive.org/: THE INTERNET ARCHIVE
* https://librivox.org/: Free audio books
* http://www.freeimages.com: Royalty-free/creative common images
* http://www.freewebtemplates.com/: Free web templates
* https://www.softaculous.com/apps/: Nice list of software
* https://www.draw.io/: Free web-based network diagram/flowchart designer (like Visio).
* http://www.emachineshop.com/machine-shop/Free-CAD-Design-Software/page100.html: Freee CAD software (also good for making gears).
* https://easyeda.com: Free circuit diagram software online
* https://www.circuitlab.com/editor/: Very simple free circuit diagram software online (can't save to file)
* ftp://ftp.ncbi.nih.gov/genomes/: National Institute of Health genome archives
* http://redobackup.org/: Bootable backup utility.
* https://www.sites.google.com/site/unoardusim/services: Arduino Uno simulator.

=== Service Manuals ===

* https://freeservicemanuals.info

== Hardware ==

* https://thepihut.com/: Raspberry Pi stuff
* https://www.newark.com/?COM=element14_store_Home: Electronics
* https://www.adafruit.com/: Electronics

== Materials ==

* http://www.tapplastics.com/: Custom plastics

== Art Tools ==

* http://www.text-image.com/convert/ascii.html: Image to ASCII art converter
* http://www.wordle.net/: word-cloud generator
* http://www.patorjk.com/software/taag/: text to ASCII art generator
* http://www.flamingtext.com/: Logo designer

== Audio Tools ==

* http://imtranslator.net/translation/text-to-speech/: text to speech

== Document Tools ==

* http://www.free-ocr.com/: Optical Character Recognition (OCR); finds text in an image
* http://www.myfonts.com/WhatTheFont/: Font identifier

== Space and Earth ==

* https://www.jasondavies.com/maps/transition/: interactive world map projections.
* https://worldview.earthdata.nasa.gov/: NASA Worldview.
* https://sdo.gsfc.nasa.gov/data/: NASA Solar Dynamics Observatory (SDO).
* https://helioviewer.org/: Interactive up-to-date view of the Sun.
* http://lmsal.com/isolsearch: Another interactive map of the Sun and solar activity.
* https://www.jwst.nasa.gov/webcam.html: Goddard Space Center clean-room webcams.
* https://science.ksc.nasa.gov/shuttle/countdown/video/: Kennedy Space Center webcams.
* http://www.isstracker.com/embed: International Space Station Tracker.
* https://spotthestation.nasa.gov/widget/: Spot The Station widget.
* http://www.ustream.tv/embed/6540154?html5ui: NASA Public-Education channel.
* http://www.ustream.tv/embed/10414700?html5ui: NASA TV Media.
* http://www.ustream.tv/embed/17074538?v=3&wmode=direct;autoplay=1: ISS Livestream 1
* http://www.ustream.tv/embed/9408562?v=3&wmode=direct;autoplay=1: ISS Livestream 2

== Privacy and Anti-Advertising ==

Scam Alerts
* https://www.consumer.ftc.gov/scam-alerts

Government Sites About Spam, Fraud, etc.
* https://attorneygeneral.nd.gov/consumer-resources/identity-theft/preventing-identity-theft
* https://www.consumer.ftc.gov/articles/0038-spam

Opt-Out Registries
* https://www.donotcall.gov/
* https://www.optoutprescreen.com
* https://dmachoice.thedma.org/
* http://www.directmail.com/mail_preference/

Privacy/Ad-blocker Tools
* https://ublock.org/: Browser plugin
* https://adblockplus.org/: Browser plugin
* https://pi-hole.net/: Network level ad-blocker (DNS-based)
* https://freek.ws/public-pi-hole/: Public hosted PiHole DNS Servers

VPN Services:
* https://www.expressvpn.com/: This company has the highest merits by my reckoning. Authorities have asked for logs and they were unable to provide it, which demonstrates that they are honest about their no-log policy. Off-shore jurisdiction: British Virgin Islands. Also, they have less usage restrictions than other VPN providers.

== Other Nifty Stuff ==

* https://www.herox.com/: A website where companies put bounties on innovation
* https://maroslaw.github.io/rainyday.js/demo012_1.html: Rainy window animation (press F11 to full-screen).
* http://www.beepbox.co/: 8-bit music synthesizer.
* http://www.eviloverlord.com/lists/overlord.html: A funny list of axioms for being a successful evil overlord.
* http://www.petittube.com/: Automatically plays random YouTube videos that have zero views, so you are literally the first viewer.
* http://www.virtualcolossus.co.uk/: Functional simulation of a Colossus Mk II.
* https://ban.ai/multics/: Virtual Multics Operating System
* http://asciicker.com/x13/: Incredible 3D ASCII based game (the "x13" is the version, use lower numbers to see older versions)
* https://ideasai.net/: An business idea generator powered by artificial intelligence (GPT-3)

External Links

2020-10-22T02:42:40Z

Beard: /* Privacy and Anti-Consumerism */

== Security Tools ==

* https://www.virustotal.com/: Multi-scanner anti-virus (no installation required).

== Programming ==

* https://fiddles.io/: Online boiler plates for all languages.
* http://cpp.sh/ : Better online boiler plate for C++.
* https://www.hex-rays.com/products/ida/support/download_freeware.shtml: Binary disassembler.
* https://www.epochconverter.com/: Unix Epoch Datetime Converter

== Web Development ==

=== CSS and Other Style Stuff ===

* http://paletton.com/: Color palette creator.
* http://www.colorzilla.com/gradient-editor/: CSS gradient generator
* http://www.cssmatic.com/: CSS Tools: gradient, border radius, texture, box shadow
* http://css3generator.com/: CSS multi-generator
* http://www.cssbuttongenerator.com/: CSS button generator
* https://www.hscripts.com/tools/drop-down-menu/index.php: JS drop-down menu generator
* http://purecssmenu.com/: CSS menu generator
* http://www.sassmeister.com/gist/5bcb7fefa9d05955f66c: Sass Lab
* https://beautifier.io/: Javescript, CSS, and HTML Unminifier/Beautifier (Code Expander)

=== Fonts ===

* https://fonts.google.com/: Google's fonts
* https://icomoon.io/: Font maker

=== Basic Tools and Info ===

* http://validator.w3.org/unicorn/: HTML validation tool
* https://www.xml-sitemaps.com/: XML sitemap generator
* https://www.browserstack.com/: Browser emulator
* http://www.ssec.edu/~tomw/java/unicode.html: Unicode List
* http://www.freeformatter.com/html-entities.html: Complete list of HTML entities

== Volunteer Computing ==

* https://boinc.berkeley.edu/: Berkeley distributed computing network (multiple projects).
* https://boinc.bakerlab.org/: Rosetta@Home protein folding.
* https://foldingathome.org/: Folding@Home protein folding.
* https://einsteinathome.org/: Einstein@Home physics simulation.
* https://lhcathome.cern.ch/lhcathome/: LHC@Home Large Hadron Collider simulation.
* https://eternagame.org/: A game that contributes to protein simulation as you play.
* https://www.zooniverse.org/: A lot of projects that allow people to actively participate in science.
* https://www.zooniverse.org/projects/zookeeper/galaxy-zoo: Help classify galaxies by examining telescope photos.
* https://www.zooniverse.org/projects/ianc2/exoplanet-explorers/: Help identify exoplanets.

== News and Information ==

* http://darksky.net/: Really nice weather report
* http://www.weathertab.com/: Long range weather forecast (1 year)
* http://www.ustream.tv/nasahdtv: NASA live stream
* http://everytimezone.com/: Visual chart of timezones
* http://www.spacerogue.net: Hacker/tech news
* http://www.freeinfosociety.com: Tons of free information

== Educational ==

* http://interactmath.com/: Free interactive math tutorials
* http://www.ptable.com/: Interactive periodic table
* http://ascendmath.com/fcm/html5/: Simple math flash cards
* https://www.desmos.com/calculator: Graphing calculator
* https://www.khanacademy.org: Free online academy (math, physics, chemistry, etc.)
* http://galaxyzoo.org: Volunteer to categorize galaxies
* http://www.planethunters.org: Volunteer to help identify exoplanets
* https://op-webtools.web.cern.ch/vistar/vistars.php: Large Hadron Collider monitor (LHC)
* http://ispy-webgl.web.cern.ch/ispy-webgl/: CMS Data Visualization
* https://www.aviso.altimetry.fr/en/data.html: Oceanic and Altimetric database

== Tutorials ==

=== Guacamole VNC Server ===

* http://guac-dev.org/doc/gug/
* https://gist.github.com/jeffersonmartin/8236574: Version 0.8.3 for Ubuntu Server
* http://www.linuxintro.org/wiki/Guacamole
* https://deviantengineer.com/2013/10/guacamole/

=== Ampache Streaming Media Server ===

* https://github.com/ampache/ampache/wiki/Installation

== Files and Software ==

* https://archive.org/: THE INTERNET ARCHIVE
* https://librivox.org/: Free audio books
* http://www.freeimages.com: Royalty-free/creative common images
* http://www.freewebtemplates.com/: Free web templates
* https://www.softaculous.com/apps/: Nice list of software
* https://www.draw.io/: Free web-based network diagram/flowchart designer (like Visio).
* http://www.emachineshop.com/machine-shop/Free-CAD-Design-Software/page100.html: Freee CAD software (also good for making gears).
* https://easyeda.com: Free circuit diagram software online
* https://www.circuitlab.com/editor/: Very simple free circuit diagram software online (can't save to file)
* ftp://ftp.ncbi.nih.gov/genomes/: National Institute of Health genome archives
* http://redobackup.org/: Bootable backup utility.
* https://www.sites.google.com/site/unoardusim/services: Arduino Uno simulator.

=== Service Manuals ===

* https://freeservicemanuals.info

== Hardware ==

* https://thepihut.com/: Raspberry Pi stuff
* https://www.newark.com/?COM=element14_store_Home: Electronics
* https://www.adafruit.com/: Electronics

== Materials ==

* http://www.tapplastics.com/: Custom plastics

== Art Tools ==

* http://www.text-image.com/convert/ascii.html: Image to ASCII art converter
* http://www.wordle.net/: word-cloud generator
* http://www.patorjk.com/software/taag/: text to ASCII art generator
* http://www.flamingtext.com/: Logo designer

== Audio Tools ==

* http://imtranslator.net/translation/text-to-speech/: text to speech

== Document Tools ==

* http://www.free-ocr.com/: Optical Character Recognition (OCR); finds text in an image
* http://www.myfonts.com/WhatTheFont/: Font identifier

== Space and Earth ==

* https://www.jasondavies.com/maps/transition/: interactive world map projections.
* https://worldview.earthdata.nasa.gov/: NASA Worldview.
* https://sdo.gsfc.nasa.gov/data/: NASA Solar Dynamics Observatory (SDO).
* https://helioviewer.org/: Interactive up-to-date view of the Sun.
* http://lmsal.com/isolsearch: Another interactive map of the Sun and solar activity.
* https://www.jwst.nasa.gov/webcam.html: Goddard Space Center clean-room webcams.
* https://science.ksc.nasa.gov/shuttle/countdown/video/: Kennedy Space Center webcams.
* http://www.isstracker.com/embed: International Space Station Tracker.
* https://spotthestation.nasa.gov/widget/: Spot The Station widget.
* http://www.ustream.tv/embed/6540154?html5ui: NASA Public-Education channel.
* http://www.ustream.tv/embed/10414700?html5ui: NASA TV Media.
* http://www.ustream.tv/embed/17074538?v=3&wmode=direct;autoplay=1: ISS Livestream 1
* http://www.ustream.tv/embed/9408562?v=3&wmode=direct;autoplay=1: ISS Livestream 2

== Privacy and Anti-Advertising ==

Scam Alerts
* https://www.consumer.ftc.gov/scam-alerts

Government Sites About Spam, Fraud, etc.
* https://attorneygeneral.nd.gov/consumer-resources/identity-theft/preventing-identity-theft
* https://www.consumer.ftc.gov/articles/0038-spam

Opt-Out Registries
* https://www.donotcall.gov/
* https://www.optoutprescreen.com
* https://dmachoice.thedma.org/
* http://www.directmail.com/mail_preference/

Privacy/Ad-blocker Tools
* https://ublock.org/: Browser plugin
* https://adblockplus.org/: Browser plugin
* https://pi-hole.net/: Network level ad-blocker (DNS-based)
* https://freek.ws/public-pi-hole/: Public hosted PiHole DNS Servers

VPN Services:
* https://www.expressvpn.com/: This company has the highest merits by my reckoning. Authorities have asked for logs and they were unable to provide it, which demonstrates that they are honest about their no-log policy. Off-shore jurisdiction: British Virgin Islands. Also, they have less usage restrictions than other VPN providers.

== Other Nifty Stuff ==

* https://maroslaw.github.io/rainyday.js/demo012_1.html: Rainy window animation (press F11 to full-screen).
* http://www.beepbox.co/: 8-bit music synthesizer.
* http://www.eviloverlord.com/lists/overlord.html: A funny list of axioms for being a successful evil overlord.
* http://www.petittube.com/: Automatically plays random YouTube videos that have zero views, so you are literally the first viewer.
* http://www.virtualcolossus.co.uk/: Functional simulation of a Colossus Mk II.
* https://ban.ai/multics/: Virtual Multics Operating System
* http://asciicker.com/x13/: Incredible 3D ASCII based game (the "x13" is the version, use lower numbers to see older versions)

Arduino

2020-09-08T22:31:09Z

Beard:

__TOC__

== Hall Effect Sensor (simple setup) ==

[[File:He_sensor_diagram.png]]
 

== Audio Shield ==

[[Arduino Audio Shield 01]]: using the Adafruit Wave Shield.

Arduino

2020-09-08T22:30:47Z

Beard:

== Hall Effect Sensor (simple setup) ==

[[File:He_sensor_diagram.png]]
 

== Audio Shield ==

[[Arduino Audio Shield 01]]: using the Adafruit Wave Shield.

Projects

2020-09-08T22:29:20Z

Beard: /* Electrical */

== Computing, Programming, and Networking ==

<big>
* [[Custom Router]]
* [[Climate Control System]]
* [[Miniand Hackberry A10]]
* [[Game Boy Zero]]

</big>

== Electrical ==

<big>
* [[Electromagnet 01]]
* [[Electromagnet 02]]
* [[Electromagnet Hard Drive Erasure]]
* [[Magnetic Viewing Film Under Microscope]]
* [[Spot Welder]]
* [[High Voltage SMores|High Voltage S'Mores]]
* [[Gameboy Power Supply]]
* [[PCB Light-Up Skull]]
* [[RGB LEDs]]
* [[Atari Punk Console]]
* [[Variable Power Supply/Battery Charger]]
* [[Alpha Radiation Detector]]
* [[TCL HDTV Repair]]
* [[Arduino Audio Shield 01]]

</big>

== 3D Printing ==

<big>
* [https://www.thingiverse.com/The_BeardBot/designs All My 3D Models on Thingiverse]
* [[Phone Mount]]
* [[CTC Upgrade 01]]
* [[CTC Upgrade 02]]
* [[Audio Jack Reinforcement]]
</big>

== Chemistry & Biology ==

<big>
* [[Tin Crystals from Tin(II) Chloride]]
* [[Recovering and Casting Indium]]

</big>

== Miscellaneous Projects ==

<big>For small, miscellaneous projects and other things, see my [[Old Blog]].</big>

Arduino Audio Shield 01

2020-09-08T22:28:43Z

Beard: Beard moved page Arduino Wave Shield 01 to Arduino Audio Shield 01

I bought the Adafruit Wave Shield and thought it would be a funny first project to have an entrance theme play every time I get home from work. I created a compilation of audio clips from the TV show Seinfeld and made them play at random when my front door opens.

<html>
<iframe width="560" height="315" src="https://youtube.com/embed/pdIsm2yy6xs" frameborder="0" allowfullscreen></iframe>
</html>

__TOC__

== Components ==
* Adafruit Wave Shield v1.1 ([https://www.adafruit.com/product/94 source])
* Arduino Uno R3 ([https://store.arduino.cc/usa/arduino-uno-rev3 source])
* AUX speaker adapter (dollar store)
* Cheap door alarm (dollar store)
* SD Card
* USB power adapter
* Cat-5 cable

== File Downloads ==

<table class="nice">
<tr>
<th>Filename</th>
<th>Description</th>
<th>Size</th>
<th>Modified</th>
<th>Link</th>
</tr>

<tr>
<td name="file">
arduino_wave1.zip
</td>
<td name="desc">Arduino code including WaveHC library.</td>
<td name="size">31KB</td>
<td name="modf">12/29/2018</td>
<td name="link">
<html><a href="https://beardedmaker.com/wiki/images/files/waveshield01/arduino_wave1.zip">
Download
</a></html>
</td>
</tr>

<tr>
<td name="file">
seinfeld_audio.zip
</td>
<td name="desc">Audio clips used in this project.</td>
<td name="size">7.9MB</td>
<td name="modf">12/29/2018</td>
<td name="link">
<html><a href="https://beardedmaker.com/wiki/images/files/waveshield01/seinfeld_audio.zip">
Download
</a></html>
</td>
</tr>

</table>

== Additional Notes ==

The files need to be in WAV format (16 bit/sample, 22050 Hz sample rate).

The SD car needs to be formatted with a FAT32 file system.

== Links ==

* Wave Shield Assembly Instructions ([https://learn.adafruit.com/adafruit-wave-shield-audio-shield-for-arduino/solder link])

== Gallery ==

[[File:DSC00580.JPG|frameless|400px]]
[[File:DSC00581.JPG|frameless|400px]]
[[File:DSC00582.JPG|frameless|400px]]
[[File:DSC00583.JPG|frameless|400px]]
[[File:DSC00584.JPG|frameless|400px]]
[[File:DSC00585.JPG|frameless|400px]]
[[File:DSC00586.JPG|frameless|400px]]
[[File:DSC00587.JPG|frameless|400px]]
[[File:DSC00588.JPG|frameless|400px]]
[[File:DSC00589.JPG|frameless|400px]]
[[File:DSC00590.JPG|frameless|400px]]

== Code ==

Here is the Arduino code. Requires the WaveHC library.
<source lang="c">

#include "WaveUtil.h"
#include "WaveHC.h"

// Pin that triggers audio
int inpin = 13;

// Delay before audio plays after trigger
int playDelay = 1500;

SdReader card;
FatVolume vol;
FatReader root;
WaveHC wave;
uint8_t dirLevel;
dir_t dirBuf;
int btnState = 0;
int fileCount = 0;
bool reset = false;

void setup() {
Serial.begin(9600);
Serial.println("\nStart");

// Set the output pins for the DAC control
// This pins are defined in the library
pinMode(2, OUTPUT);
pinMode(3, OUTPUT);
pinMode(4, OUTPUT);
pinMode(5, OUTPUT);

pinMode(inpin, INPUT);

if (!card.init())
{
Serial.println("Card init. failed!");
while(1); // Halt
}

// Enable optimize read
// Some cards may timeout. Disable if you're having problems
card.partialBlockRead(true);

// Look for a FAT partition
uint8_t part;
for (part = 0; part < 5; part++)
{
if (vol.init(card, part))
{
break;
}
}
if (part == 5)
{
Serial.println("No valid FAT partition!");
while(1); // Halt
}

Serial.print("Using partition ");
Serial.print(part, DEC);
Serial.print(", type is FAT");
Serial.println(vol.fatType(),DEC);

// Try to open the root directory
if (!root.openRoot(vol))
{
Serial.println("Can't open root dir!");
while(1); // Halt
}

// Print the file names
Serial.println("Files found:");
dirLevel = 0;
lsR(root);

// Seed the random number generator by reading an analog pin
randomSeed(analogRead(A0));

// Count the number of files
root.rewind();
fileCount = countFiles(root);
Serial.print("File count: ");
Serial.println(fileCount);
}

void loop() {
btnState = digitalRead(inpin);
if (btnState == HIGH)
{
Serial.println("Door Closed; wait");
reset = true;
delay(200);

while (reset == true)
{
btnState = digitalRead(inpin);
if (btnState == LOW)
{
Serial.println("Door Open; play and wait");
delay(playDelay);
root.rewind();
playRandom(root, fileCount);
Serial.println();
reset = false;
delay(500);
break;
}
else
{
continue;
}
}
}
}

/*
* Play a random file
*/
void playRandom(FatReader &dir, int fileCount)
{
FatReader file;

int playFile = random(1, fileCount);
int fileIter = 1;

// Read every file in the directory one at a time
while (dir.readDir(dirBuf) > 0)
{
// skip . and .. directories
if (dirBuf.name[0] == '.')
{
continue;
}

if (fileIter < playFile)
{
fileIter++;
continue;
}

if (!file.open(vol, dirBuf))
{
Serial.println("file.open failed");
while(1); // Halt
}

Serial.print("Playing ");
printEntryName(dirBuf);
if (!wave.create(file))
{
Serial.print(" Not a valid WAV");
}
else
{
// playing occurs in interrupts
wave.play();

while (wave.isplaying)
{
putstring(".");
delay(100);
}

if (wave.errors)
{
Serial.println(wave.errors);
}
}
break;
}
}

/*
* Count files on the SD card
*/
int countFiles(FatReader &dir)
{
int fileCount = 0;
FatReader file;
while (dir.readDir(dirBuf) > 0)
{
if (dirBuf.name[0] == '.' || !file.open(vol, dirBuf))
{
continue;
}
fileCount++;
}
return fileCount;
}

/*
* List files recursively
*/
void lsR(FatReader &d)
{
// indicates the level of recursion
int8_t r;

while ((r = d.readDir(dirBuf)) > 0)
{
// skip subdirs . and ..
if (dirBuf.name[0] == '.')
{
continue;
}

for (uint8_t i = 0; i < dirLevel; i++)
{
Serial.print(' ');
}

printEntryName(dirBuf);
Serial.println();

// Recurse on any direcory
if (DIR_IS_SUBDIR(dirBuf))
{
FatReader s;
dirLevel += 2;
if (s.open(vol, dirBuf))
{
lsR(s);
}
dirLevel -=2;
}
}
}
</source>

Arduino Wave Shield 01

2020-09-08T22:28:43Z

Beard: Beard moved page Arduino Wave Shield 01 to Arduino Audio Shield 01

#REDIRECT [[Arduino Audio Shield 01]]

APC Smart-UPS

2020-08-31T18:44:16Z

Beard: /* Line Input Sensitivity */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

Will be adding notes here soon.

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using your package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should see the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
0: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

On the second line, the number N on the far left corresponds to <code>/dev/ttyUSBN</code>. Mine shows <code>0:</code> so I would use <code>/dev/ttyUSB0</code>. When you unplug the cable and plug it back in there's a chance that the number will change. I've also seen the number change when starting and stopping apcupsd, but I'm not sure of the cause.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in your device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the software runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Hard Reset =

This is the process to perform a hard reset (a.k.a. "brain dead", hard reboot, discharge cycle). You may want to try this process when troubleshooting a UPS that is acting strangely. It sometimes solves the issue.

# Turn the UPS off using the power button.
# Unplug everything from the UPS (including any serial, USB, or network cables).
# Unplug the UPS from the wall outlet.
# Disconnect the batteries.
# Press and hold the power button for at least 5 seconds.
# Reconnect the batteries.
# Plug the UPS into the wall outlet.
# Turn on the UPS.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (for high), "M" (for medium), or "L" (for low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section. If you don't have a 4-battery harness, you may want to check out my [[#3D_Printed_Parts|3D Printed Parts]].

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-31T18:43:36Z

Beard: /* Line Input Sensitivity */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

Will be adding notes here soon.

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using your package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should see the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
0: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

On the second line, the number N on the far left corresponds to <code>/dev/ttyUSBN</code>. Mine shows <code>0:</code> so I would use <code>/dev/ttyUSB0</code>. When you unplug the cable and plug it back in there's a chance that the number will change. I've also seen the number change when starting and stopping apcupsd, but I'm not sure of the cause.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in your device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the software runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Hard Reset =

This is the process to perform a hard reset (a.k.a. "brain dead", hard reboot, discharge cycle). You may want to try this process when troubleshooting a UPS that is acting strangely. It sometimes solves the issue.

# Turn the UPS off using the power button.
# Unplug everything from the UPS (including any serial, USB, or network cables).
# Unplug the UPS from the wall outlet.
# Disconnect the batteries.
# Press and hold the power button for at least 5 seconds.
# Reconnect the batteries.
# Plug the UPS into the wall outlet.
# Turn on the UPS.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section. If you don't have a 4-battery harness, you may want to check out my [[#3D_Printed_Parts|3D Printed Parts]].

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-31T18:42:28Z

Beard: /* Hard Reset */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

Will be adding notes here soon.

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using your package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should see the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
0: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

On the second line, the number N on the far left corresponds to <code>/dev/ttyUSBN</code>. Mine shows <code>0:</code> so I would use <code>/dev/ttyUSB0</code>. When you unplug the cable and plug it back in there's a chance that the number will change. I've also seen the number change when starting and stopping apcupsd, but I'm not sure of the cause.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in your device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the software runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Hard Reset =

This is the process to perform a hard reset (a.k.a. "brain dead", hard reboot, discharge cycle). You may want to try this process when troubleshooting a UPS that is acting strangely. It sometimes solves the issue.

# Turn the UPS off using the power button.
# Unplug everything from the UPS (including any serial, USB, or network cables).
# Unplug the UPS from the wall outlet.
# Disconnect the batteries.
# Press and hold the power button for at least 5 seconds.
# Reconnect the batteries.
# Plug the UPS into the wall outlet.
# Turn on the UPS.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section. If you don't have a 4-battery harness, you may want to check out my [[#3D_Printed_Parts|3D Printed Parts]].

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-31T18:42:08Z

Beard: /* Hard Reset */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

Will be adding notes here soon.

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using your package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should see the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
0: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

On the second line, the number N on the far left corresponds to <code>/dev/ttyUSBN</code>. Mine shows <code>0:</code> so I would use <code>/dev/ttyUSB0</code>. When you unplug the cable and plug it back in there's a chance that the number will change. I've also seen the number change when starting and stopping apcupsd, but I'm not sure of the cause.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in your device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the software runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Hard Reset =

This is the process to perform a hard reset (a.k.a. "brain dead", hard reboot, discharge cycle). You may want to try this process when troubleshooting a UPS that is acting strangely. It sometimes solves the issue.

# Turn the UPS off using the power button.
# Unplug everything from the UPS (including any serial, USB, or network cables).
# Unplug the UPS from the wall outlet.
# Disconnect the batteries.
# Press and hold the power button for at least 5 seconds.
# Reconnect the batteries.
# Plug the UPS into mains power.
# Turn on the UPS.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section. If you don't have a 4-battery harness, you may want to check out my [[#3D_Printed_Parts|3D Printed Parts]].

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-31T18:40:49Z

Beard: /* Manual Runtime Calibration */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

Will be adding notes here soon.

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using your package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should see the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
0: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

On the second line, the number N on the far left corresponds to <code>/dev/ttyUSBN</code>. Mine shows <code>0:</code> so I would use <code>/dev/ttyUSB0</code>. When you unplug the cable and plug it back in there's a chance that the number will change. I've also seen the number change when starting and stopping apcupsd, but I'm not sure of the cause.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in your device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the software runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Hard Reset =

This is the process to perform a hard reset (a.k.a. "brain dead", hard reboot, discharge cycle). You may want to try this process when troubleshooting a UPS that is acting strangely. It sometimes solves the issue.

# Turn the UPS off using the power button.
# Unplug everything from the UPS (including any serial, USB, or network cables).
# Unplug the UPS from mains power.
# Disconnect the batteries.
# Press and hold the power button for at least 5 seconds.
# Reconnect the batteries.
# Plug the UPS into mains power.
# Turn on the UPS.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section. If you don't have a 4-battery harness, you may want to check out my [[#3D_Printed_Parts|3D Printed Parts]].

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-31T18:36:42Z

Beard: /* Finding Your Serial Port */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

Will be adding notes here soon.

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using your package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should see the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
0: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

On the second line, the number N on the far left corresponds to <code>/dev/ttyUSBN</code>. Mine shows <code>0:</code> so I would use <code>/dev/ttyUSB0</code>. When you unplug the cable and plug it back in there's a chance that the number will change. I've also seen the number change when starting and stopping apcupsd, but I'm not sure of the cause.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in your device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Hard Reset =

This is the process to perform a hard reset (a.k.a. "brain dead", hard reboot, discharge cycle). You may want to try this process when troubleshooting a UPS that is acting strangely. It sometimes solves the issue.

# Turn the UPS off using the power button.
# Unplug everything from the UPS (including any serial, USB, or network cables).
# Unplug the UPS from mains power.
# Disconnect the batteries.
# Press and hold the power button for at least 5 seconds.
# Reconnect the batteries.
# Plug the UPS into mains power.
# Turn on the UPS.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section. If you don't have a 4-battery harness, you may want to check out my [[#3D_Printed_Parts|3D Printed Parts]].

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-31T18:35:53Z

Beard: /* Finding Your Serial Port */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

Will be adding notes here soon.

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using your package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should see the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
0: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

On the second line, the number N on the far left corresponds to <code>/dev/ttyUSBN</code>. Mine shows <code>0:</code> so I would use <code>/dev/ttyUSB0</code>. When you unplug the cable and plug it back in there's a chance that the number will change. I've also seen the number change when starting and stopping apcupsd, but I'm not sure of the cause.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in your device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Hard Reset =

This is the process to perform a hard reset (a.k.a. "brain dead", hard reboot, discharge cycle). You may want to try this process when troubleshooting a UPS that is acting strangely. It sometimes solves the issue.

# Turn the UPS off using the power button.
# Unplug everything from the UPS (including any serial, USB, or network cables).
# Unplug the UPS from mains power.
# Disconnect the batteries.
# Press and hold the power button for at least 5 seconds.
# Reconnect the batteries.
# Plug the UPS into mains power.
# Turn on the UPS.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section. If you don't have a 4-battery harness, you may want to check out my [[#3D_Printed_Parts|3D Printed Parts]].

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-31T18:35:12Z

Beard: /* Finding Your Serial Port */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

Will be adding notes here soon.

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using your package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should see the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
0: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

On the second line, the number N on the far left corresponds to <code>/dev/ttyUSBN</code>. Mine shows <code>0:</code> so I would use <code>/dev/ttyUSB0</code>. When you unplug the cable and plug it back in there's a chance that the number will change. I've also seen the number change when starting and stopping apcupsd, but I'm not sure of the cause.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in you device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Hard Reset =

This is the process to perform a hard reset (a.k.a. "brain dead", hard reboot, discharge cycle). You may want to try this process when troubleshooting a UPS that is acting strangely. It sometimes solves the issue.

# Turn the UPS off using the power button.
# Unplug everything from the UPS (including any serial, USB, or network cables).
# Unplug the UPS from mains power.
# Disconnect the batteries.
# Press and hold the power button for at least 5 seconds.
# Reconnect the batteries.
# Plug the UPS into mains power.
# Turn on the UPS.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section. If you don't have a 4-battery harness, you may want to check out my [[#3D_Printed_Parts|3D Printed Parts]].

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-31T18:33:50Z

Beard: /* Finding Your Serial Port */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

Will be adding notes here soon.

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using your package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should see the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
0: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

On the second line, the number N on the far left corresponds to <code>/dev/ttyUSBN</code>. Mine shows <code>0:</code> so I would use <code>/dev/ttyUSB0</code>. When you unplug the cable and plug it back in there's a chance that the number will change.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in you device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Hard Reset =

This is the process to perform a hard reset (a.k.a. "brain dead", hard reboot, discharge cycle). You may want to try this process when troubleshooting a UPS that is acting strangely. It sometimes solves the issue.

# Turn the UPS off using the power button.
# Unplug everything from the UPS (including any serial, USB, or network cables).
# Unplug the UPS from mains power.
# Disconnect the batteries.
# Press and hold the power button for at least 5 seconds.
# Reconnect the batteries.
# Plug the UPS into mains power.
# Turn on the UPS.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section. If you don't have a 4-battery harness, you may want to check out my [[#3D_Printed_Parts|3D Printed Parts]].

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-31T18:31:22Z

Beard: /* Monitoring Using Apcupsd (Linux) */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

Will be adding notes here soon.

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using your package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should look for the <code>port:</code> in the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
0: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

On the second line, the number N at the very beginning of the line corresponds to <code>/dev/ttyUSBN</code>. Mine shows <code>0:</code> so I would use <code>/dev/ttyUSB0</code>. When you unplug the cable and plug it back in there's a chance that the number will change.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in you device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Hard Reset =

This is the process to perform a hard reset (a.k.a. "brain dead", hard reboot, discharge cycle). You may want to try this process when troubleshooting a UPS that is acting strangely. It sometimes solves the issue.

# Turn the UPS off using the power button.
# Unplug everything from the UPS (including any serial, USB, or network cables).
# Unplug the UPS from mains power.
# Disconnect the batteries.
# Press and hold the power button for at least 5 seconds.
# Reconnect the batteries.
# Plug the UPS into mains power.
# Turn on the UPS.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section. If you don't have a 4-battery harness, you may want to check out my [[#3D_Printed_Parts|3D Printed Parts]].

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

Working

2020-08-31T18:29:44Z

Beard:

__NOTOC__
Pages that I am currently working on.

Reminders:
* Search for notes in square brackets [] for things that need completion.
* Search for headers with no text under them.
* The <code><source></code> tag is a synonym for <code><syntaxhighlight></code>.
* Add line numbers like this: <code><source lang="shell" line>echo "hi"</source></code>
* [[Mediawiki|Mediawiki Tutorials]]

Licenses:
* GNU GPL 2.0 ([https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt external], [https://beardedmaker.com/gpl-2.0.txt local]): <nowiki>https://beardedmaker.com/gpl-2.0.txt</nowiki>
* GNU GPL 3.0 ([https://www.gnu.org/licenses/gpl-3.0.txt external], [https://beardedmaker.com/gpl-3.0.txt local]): <nowiki>https://beardedmaker.com/gpl-3.0.txt</nowiki>

Special Pages:
* <html><a href="https://beardedmaker.com/wiki/index.php/MediaWiki:Common.css">Global CSS Stylesheet</a></html>
* <html><a href="https://beardedmaker.com/wiki/index.php/MediaWiki:Sidebar">Sidebar Navigation List</a></html>
* <html><a href="https://beardedmaker.com/wiki/index.php/MediaWiki:Mainpage">Main Page Definition</a></html>
* <html><a href="https://beardedmaker.com/wiki/index.php?title=Special:Version">Versions for Everything</a></html>
* <html><a href="https://beardedmaker.com/wiki/index.php?title=Special:BatchUpload">Batch Upload</a></html>

== Completed but needs Revision/Additions ==

* [[3D Printing]]
* [[Run a Script on Startup or Shutdown]] (add links to [[VirtualBox]] and [[Backup NAS Mini]])

== Projects ==

=== Computing, Programming, and Networking ===

* [[Camera Security System]]
* [[Volunteer Computing]]
* [[Backup NAS Mini]]

=== Electrical ===

* [[Tesla Coil]]
* [[Geiger Counter Sound Mod]]
* [[DIY Geiger Counter]]

=== 3D Printing ===

=== Chemistry & Biology ===

* [[Germicidal UV Lamp & Bacterial Incubator]]
* [[Guide to Collecting the Elements]]

== Tutorials ==

* [[APC Smart-UPS]]

APC Smart-UPS

2020-08-27T16:01:46Z

Beard: /* Monitoring Using PowerChute (Windows) */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

Will be adding notes here soon.

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using you package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should look for the <code>port:</code> in the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
0: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

On the second line, the number N at the very beginning of the line corresponds to <code>/dev/ttyUSBN</code>. Mine shows <code>0:</code> so I would use <code>/dev/ttyUSB0</code>. When you unplug the cable and plug it back in there's a chance that the number will change.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in you device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Hard Reset =

This is the process to perform a hard reset (a.k.a. "brain dead", hard reboot, discharge cycle). You may want to try this process when troubleshooting a UPS that is acting strangely. It sometimes solves the issue.

# Turn the UPS off using the power button.
# Unplug everything from the UPS (including any serial, USB, or network cables).
# Unplug the UPS from mains power.
# Disconnect the batteries.
# Press and hold the power button for at least 5 seconds.
# Reconnect the batteries.
# Plug the UPS into mains power.
# Turn on the UPS.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section. If you don't have a 4-battery harness, you may want to check out my [[#3D_Printed_Parts|3D Printed Parts]].

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-25T05:03:05Z

Beard: /* Hard Reset */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using you package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should look for the <code>port:</code> in the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
0: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

On the second line, the number N at the very beginning of the line corresponds to <code>/dev/ttyUSBN</code>. Mine shows <code>0:</code> so I would use <code>/dev/ttyUSB0</code>. When you unplug the cable and plug it back in there's a chance that the number will change.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in you device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Hard Reset =

This is the process to perform a hard reset (a.k.a. "brain dead", hard reboot, discharge cycle). You may want to try this process when troubleshooting a UPS that is acting strangely. It sometimes solves the issue.

# Turn the UPS off using the power button.
# Unplug everything from the UPS (including any serial, USB, or network cables).
# Unplug the UPS from mains power.
# Disconnect the batteries.
# Press and hold the power button for at least 5 seconds.
# Reconnect the batteries.
# Plug the UPS into mains power.
# Turn on the UPS.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section. If you don't have a 4-battery harness, you may want to check out my [[#3D_Printed_Parts|3D Printed Parts]].

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-25T05:00:43Z

Beard: /* Manual Runtime Calibration */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using you package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should look for the <code>port:</code> in the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
0: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

On the second line, the number N at the very beginning of the line corresponds to <code>/dev/ttyUSBN</code>. Mine shows <code>0:</code> so I would use <code>/dev/ttyUSB0</code>. When you unplug the cable and plug it back in there's a chance that the number will change.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in you device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Hard Reset =

This is the process to perform a hard reset (a.k.a. "brain dead", hard reboot, discharge cycle):

# Turn the UPS off using the power button.
# Unplug everything from the UPS (including any serial, USB, or network cables).
# Unplug the UPS from mains power.
# Disconnect the batteries.
# Press and hold the power button for at least 5 seconds.
# Reconnect the batteries.
# Plug the UPS into mains power.
# Turn on the UPS.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section. If you don't have a 4-battery harness, you may want to check out my [[#3D_Printed_Parts|3D Printed Parts]].

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-25T03:56:44Z

Beard: /* Finding Your Serial Port */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using you package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should look for the <code>port:</code> in the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
0: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

On the second line, the number N at the very beginning of the line corresponds to <code>/dev/ttyUSBN</code>. Mine shows <code>0:</code> so I would use <code>/dev/ttyUSB0</code>. When you unplug the cable and plug it back in there's a chance that the number will change.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in you device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section. If you don't have a 4-battery harness, you may want to check out my [[#3D_Printed_Parts|3D Printed Parts]].

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-25T03:54:59Z

Beard: /* Finding Your Serial Port */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using you package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should look for the <code>port:</code> in the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
0: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

On the second line, the number N at the very beginning of the line corresponds to <code>/dev/ttyUSBN</code>. Mine shows <code>0:</code> so I would use <code>/dev/ttyUSB0</code>.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in you device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section. If you don't have a 4-battery harness, you may want to check out my [[#3D_Printed_Parts|3D Printed Parts]].

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-25T03:39:09Z

Beard: /* Converting a 2-Battery UPS to a 4-Battery UPS */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using you package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should look for the <code>port:</code> in the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
1: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

Mine shows <code>port:0</code> which corresponds to <code>/dev/ttyUSB0</code>.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in you device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section. If you don't have a 4-battery harness, you may want to check out my [[#3D_Printed_Parts|3D Printed Parts]].

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-25T03:37:20Z

Beard: /* 3D Printed Parts */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using you package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should look for the <code>port:</code> in the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
1: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

Mine shows <code>port:0</code> which corresponds to <code>/dev/ttyUSB0</code>.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in you device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section.

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= <html><a name="3D_Printed_Parts"></a></html> 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-25T03:35:50Z

Beard: /* Reading UPS Status */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using you package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should look for the <code>port:</code> in the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
1: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

Mine shows <code>port:0</code> which corresponds to <code>/dev/ttyUSB0</code>.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in you device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank or say COMMLOST. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section.

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-25T03:25:19Z

Beard: /* Finding Your Serial Port */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using you package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should look for the <code>port:</code> in the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
1: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

Mine shows <code>port:0</code> which corresponds to <code>/dev/ttyUSB0</code>.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in you device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used <code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section.

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-25T03:24:59Z

Beard: /* Finding Your Serial Port */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using you package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following sections, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

If you're using a serial to USB adapter, you can run the following command:
<source>
sudo less /proc/tty/driver/usbserial
</source>

You should look for the <code>port:</code> in the following output:
<pre class="out">
usbserinfo:1.0 driver:2.0
1: module:ch341 name:"ch341-uart" vendor:1a86 product:7523 num_ports:1 port:0 path:usb-0000:00:1d.0-1.2
</pre>

Mine shows <code>port:0</code> which corresponds to <code>/dev/ttyUSB0</code>.

Another way you can do it, because USB serial devices only show up in /dev when they are connected, is to see which files appear when you plug in you device. Leave the cable unplugged from your computer, then run the command below. It will print a newline and pause. While it's paused plug in the cable then press Enter:
<source>
diff <(ls /dev) <(read;ls /dev)|grep ">"
</source>

You will see output like this:
<pre class="out">
> serial
> ttyUSB0
</pre>

I found that <code>/dev/serial</code> did not work, so I used </code>/dev/ttyUSB0</code>.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section.

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-25T03:11:08Z

Beard: /* Configuring Apcupsd */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using you package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following steps, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

I found that if I'm using a USB cable, I need to set the DEVICE to <code>/dev/ttyUSB0</code>.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

If you're using a Smart serial cable with a serial-to-USB adapter, I found that these configurations worked:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyUSB0
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section.

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-25T03:07:04Z

Beard: /* Configuring Apcupsd */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using you package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following steps, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". Then set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section.

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-24T06:26:41Z

Beard: /* Disable Terminal Messages (Wall) */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using you package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following steps, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". THen set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section.

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= 3D Printed Parts =

Modular Battery Harness (2-battery or 4-battery): https://www.thingiverse.com/thing:4578235 
[[File:DSC06104.JPG|200px]]

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

File:DSC06104.JPG

2020-08-24T06:25:30Z

Beard:

APC Smart-UPS

2020-08-24T06:14:36Z

Beard: /* Battery Wiring */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using you package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following steps, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". THen set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section.

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg|300px]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

APC Smart-UPS

2020-08-24T06:13:49Z

Beard: /* Battery Wiring */

The following information applies to all APC Smart-UPS models. Most of this I personally tested using a Smart-UPS SC 1500 and a Smart-UPS 2200 (both are rack mount units).

= Console Cables =

To configure a Smart-UPS, you need to connect via console cable. Depending on your model, the unit may have a USB port, serial port, or both.

== USB to RJ50 Cable ==

The Smart-UPS uses a non-standard USB to RJ50 cable, which looks similar to an RJ45 but has 10 pins instead of 8. You might need to order a cable directly from APC or find a used one. The model number I ordered was AP9827 940-0127E and I can confirm it works on both Smart-UPS SC 1500 and 2200.

[[File:AP9827_940-0127E.jpg|frameless]]

If you happen to have an RJ50 connector and a spare USB cable, you could make your own with the following pinout:

[[File:APC_USB_Pinout.jpg|550px]]

== Serial Cable ==

IMPORTANT: You CANNOT connect a normal serial cable to the Smart-UPS. If you do connect a normal serial cable and terminate both ends, the Smart-UPS will likely shut down or exhibit other strange behaviors.

The cable required for a serial port on a Smart-UPS is also proprietary and has a non-standard pinout. You need a "Smart Signalling" capable serial cable (RS-232). The model number I ordered was 940-1524C and I can confirm it works with the Smart-UPS SC 1500 and 2200. Note that the "15" in that model number is the length of the cable, so any model that varies in those digits will work the same.

If you want to create your own serial cable, you will need a male DB9 connector and a female DB9 connector. Wire them up with the following pinout:

[[File:APC_Serial_Pinout.jpg]]

= Monitoring Using PowerChute (Windows) =

= Monitoring Using Apcupsd (Linux) =

Apcupsd is an open source alternative to APC's PowerChute software for monitoring and configuring APC UPS devices. You can install it using you package manager. Note: The following tutorials were performed on Debian-based Linux.

Install using apt-get:
<source>
sudo apt-get install apcupsd
</source>

== Finding Your Serial Port ==

Before you can configure apcupsd, you will need to figure out what serial port you're connected to. This is easy if you have only one serial device. The device file will be named something like <code>/dev/ttySN</code> where N is a number. Most likely you will have many serial ttys in the /dev directory, but most of them will not actually have a recognized UART device attached.

To find which serial devices have a UART, you can run to following command:

<source>
sudo less /proc/tty/driver/serial
</source>

You will see an output similar this:
<pre class="output">
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:unknown port:000002F8 irq:3
2: uart:unknown port:000003E8 irq:4
3: uart:unknown port:000002E8 irq:3
4: uart:ST16650V2 port:0000E030 irq:16 tx:0 rx:0
5: uart:ST16650V2 port:0000E020 irq:17 tx:121720 rx:670672 brk:4
6: uart:unknown port:00000000 irq:0
...
</pre>

Ignore the ones that say "unknown." The ones that actually have a UART device will display the UART model. If you have more than one, you might need to use a process of elimination. I happen to know that my device is on line 5. The number on the far left corresponds to the device number N in the file name <code>/dev/ttySN</code>. So I will configure apcupsd to use the device <code>/dev/ttyS5</code>. If you're not sure which device is the right one, you can go ahead and continue [[#Configuring-Apcupsd|Configuring Apcupsd]] as I've specified in the following steps, and then follow the steps in [[#Reading-UPS-Status|Reading UPS Status]] to figure out if you've chosen the right device number.

== <html><a name="Configuring-Apcupsd"></a></html> Configuring Apcupsd ==

Before you start the apcupsd service there are a couple files you need to edit.

Edit the file <code>/etc/apcupsd/apcupsd.conf</code> and change the following lines to fit your needs:
<source>
UPSCABLE usb
UPSTYPE usb
DEVICE /dev/ttyS0
</source>

The file contains comments that very thoroughly explain what parameters are available for each option.

If you're using a serial cable, the UPSCABLE option needs to have the right model and UPSTYPE should be "apcsmart". THen set the DEVICE option to device file.

Here are my settings for serial:
<source>
UPSCABLE 940-1524C
UPSTYPE apcsmart
DEVICE /dev/ttyS5
</source>

Now you need to edit the file <code>/etc/default/apcupsd</code>.

Set the value to "yes":
<source>
ISCONFIGURED=yes
</source>

You are now ready to start the apcupsd service.

== Starting/Stopping Apcupsd ==

Start apcupsd:
<source>
sudo systemctl start apcupsd
</source>

Stop apcupsd:
<source>
sudo systemctl stop apcupsd
</source>

== <html><a name="Reading-UPS-Status"></a></html> Reading UPS Status ==

Once you have apcupsd configured and running, you can get a readout of information about the UPS by running the command:

<source>
sudo apcaccess
</source>

If your APC is connected properly, you will see an output like this:
<pre class="result">
APC : 001,048,1107
DATE : 2020-07-27 22:05:34 -0700
HOSTNAME : neuromancer
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : UPS_IDEN
CABLE : Custom Cable Smart
DRIVER : APC Smart UPS (any)
UPSMODE : Stand Alone
STARTTIME: 2020-07-27 22:05:27 -0700
MODEL : Smart-UPS SC1500
STATUS : ONLINE
LINEV : 122.0 Volts
LOADPCT : 0.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 956.0 Minutes
...
</pre>

If your APC is not connected, you will get a bunch of nonsense values, such as 0 volts, and the STATUS might be blank. This is how you know if you have configured apcupsd with the correct serial port. Note that it takes about 10 seconds after starting the apcupsd service before you will see proper values when running the apcaccess command.

= Accessing UPS Configuration Terminal =

The configuration terminal allows you to make configuration changes and perform a runtime calibration.

First you must stop the ascupsd service if it's running:
<source>
sudo systemctl stop apcupsd
</source>

Now run the apctest command:
<source>
sudo apctest
</source>

You will be presented with several options:
<pre class="result">
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
Q) Quit
</pre>

= <html><a name="Software_Runtime_Calibration"></a></html> Software Runtime Calibration =

Calibrating the APC makes sure that the system has a good estimate of how long the unit can run on the installed batteries with a given load. You should perform a calibration about once or twice a year and every time you install new batteries.

Procedure:

# Make sure the batteries are fully charged.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>2) Perform a Battery Runtime Calibration</code>.
# The batteries will drain entirely and the APC will eventually reboot and start charging the batteries again. This process must not be interrupted.
# Once the batteries are fully changed, the calibration is complete.

= <html><a name="Manual_Runtime_Calibration"></a></html> Manual Runtime Calibration =

This procedure is an alternative to the runtime calibration.

Procedure:

# With batteries installed, plug the unit into a power outlet and leave it on and charging for at least 24 hours.
# Disconnect any serial or USB cables from the unit.
# Plug a device into the APC that draws at least a 30% load and will not fluctuate by more than +/- 5%. Do not use an essential device as the calibration process will cause an abrupt shutdown. Something like lamps or a TV will do.
# Disconnect the APC from the wall outlet to force it to run on battery power.
# Allow the APC to run on batteries until it completely shuts off.
# Remove the load drawing devices and plug the APC back into the wall outlet.
# Allow the APC to charge until the batteries are fully charged. It will charge quicker if the unit is turned off.

= Line Input Sensitivity =

The APC senses irregularities in the power input and will switch to batteries power if the irregularities go beyond a certain threshold. Using the configuration terminal you can change the sensitivity of this threshold.

The reason you might do this is if you have an old unit the capacitors in the sensing circuit might be wearing out and falsely triggering the failover. If this is happening to your unit, you might see it flapping back and forth between line and battery power, or it may even be stuck on battery power. If this is the case, you can try lowering the sensitivity using this procedure.

First you can check the current sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Make sure apcupsd is running.
# Run the command <code>sudo apcaccess</code>.
# Look for the line <code>SENSE : High</code>. The possible values are High, Medium, and Low.

To change the sensitivity setting:
# Connect your PC to the APC via serial or USB cable.
# Stop the apcupsd service if it is running.
# Run the command <code>sudo apctest</code>.
# From the terminal, choose the option <code>5) Program EEPROM</code>.
# Choose the option <code>4) Change sensitivity</code>.
# At the prompt "Enter new sensitivity:" enter either a capital "H" (high), "M" (medium), or "L" (low). It will take a few seconds.
# You can now exit, start apcupsd again, and run the apcaccess command to confirm the change.

If setting it to medium doesn't work, try setting to to low. If this does not solve your problem, you're looking at needing to replace capacitors.

= Converting a 2-Battery UPS to a 4-Battery UPS =

For a long time, I had an APC Smart-UPS SC 1500, which holds 4 batteries. When it started having issues I discovered that you can buy the cheaper model APC Smart-UPS SN 1000, which holds 2 batteries, and it's actually trivial to convert it to a 4-battery unit.

If you open up the case and look in the battery bay you will see a metal plate. Simply remove this plate. That's it!

[[File:APC_SN1000_Plate.jpg|500px]]

The only additional thing you need to do is perform a [[#Software_Runtime_Calibration|Software Runtime Calibration]] or a [[#Manual_Runtime_Calibration|Manual Runtime Calibration]] with the new batteries installed.

Also, if you're going to wire up your own battery harness, see the [[#Battery_Wiring|Battery Wiring]] section.

= <html><a name="Battery_Wiring"></a></html> Battery Wiring =

== 2-Battery Wiring ==

[[File:APC_Smart-UPS_2-Battery_Wiring_Diagram.jpg]]

== 4-Battery Wiring ==

[[File:APC_Smart-UPS_SC1500_Battery_Wiring_Diagram.jpg|500px]]

= Event Handling and Notifications =

When an event occurs, apcupsd will run the script <code>/etc/apcupsd/apccontrol</code> with a command line argument that invokes code within the corresponding switch case (read the script to see the available arguments).

Before apcupsd invokes apccontrol, it will look for a file in <code>/etc/apcupsd</code> that has the same name as the command line argument that it will pass to apccontrol and run that script first. For example, before apcupsd invokes <code>/etc/apcupsd/apccontrol doshutdown</code> it will look for a file called <code>/etc/apcupsd/doshutdown</code> and run it if it exists. This way you can easily customize notifications and other actions to occur before apcupsd shuts your computer down.

Another example: when the batteries need to be changed apcupsd will run the script <code>/etc/apcupsd/changeme</code>. Edit this script to add a customized notification. I added some code to send me a text message.

If you create a new script, be sure it has the correct ownership and permissions (according to the permissions of the scripts that are installed with apcupsd):
<source>
cd /etc/apcupsd
touch doshutdown
chown root:root doshutdown
chmod 755 doshutdown
</source>

= Disable Terminal Messages (Wall) =

Apcupsd uses the <code>wall</code> command to push a message to the terminals of every user on the system. If you don't want this, you can edit the file <code>/etc/apcupsd/apccontrol</code> and replace the line:
<source>
WALL=wall
</source>

With:
<source>
WALL=:
</source>

= Links And Files =

* Calibration: https://www.apc.com/us/en/faqs/FA284198/
* Serial Pinout: https://pinoutguide.com/UPS/apc_smart_cable_pinout.shtml
* Apcupsd Manual: http://www.apcupsd.org/manual/manual.pdf
* Customized Event Handling: http://apcupsd.org/manual/manual.html#customizing-event-handling

File:APC Smart-UPS 2-Battery Wiring Diagram.jpg

2020-08-24T06:12:56Z

Beard:

CSS Styles

2020-08-13T01:15:15Z

Beard: /* Collapsible Section */

== Apply CSS Based on Attribute ==

This just seems like less typing to me. Why type out class="something"? Especially in a wiki where you have to type it all the time.

CSS:
<source lang="css">
div[red] {
color: red;
}
div[blue] {
color: blue;
}
</source>

HTML:
<source lang="html">
<div red>
This should be red.
</div>
<div blue>
This should be blue.
</div>
</source>

RESULT:
<div class="box">
This should be red. 
This should be blue.
</div>

== Absolute Center (via Flexbox) ==

<syntaxhighlight lang="css">
.absolute-center {

/* Internet Explorer 10 */
display:-ms-flexbox;
-ms-flex-pack:center;
-ms-flex-align:center;

/* Firefox */
display:-moz-box;
-moz-box-pack:center;
-moz-box-align:center;

/* Safari, Opera, and Chrome */
display:-webkit-box;
-webkit-box-pack:center;
-webkit-box-align:center;

/* W3C */
display:box;
box-pack:center;
box-align:center;

}
</syntaxhighlight>

== Wrap Text in <pre> Tag ==

<syntaxhighlight lang="css">
/* wrap text in pre tag, good for mobile because pre won't extend beyond screen width */
pre.wrap {
white-space: pre-wrap; /* Since CSS 2.1 */
white-space: -moz-pre-wrap; /* Mozilla, since 1999 */
white-space: -pre-wrap; /* Opera 4-6 */
white-space: -o-pre-wrap; /* Opera 7 */
word-wrap: break-word; /* Internet Explorer 5.5+ */
}
</syntaxhighlight>

== Collapsible Section ==

<source lang="css">
<!DOCTYPE html>
<html>
<head>
<title>TEST 2</title>
<style>
@font-face {
font-family: 'Open Sans';
font-style: normal;
font-weight: 300;
src: local('Open Sans Light'), local('OpenSans-Light'), url(https://fonts.gstatic.com/s/opensans/v13/DXI1ORHCpsQm3Vp6mXoaTegdm0LZdjqr5-oayXSOefg.woff2) format('woff2');
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215, U+E0FF, U+EFFD, U+F000;
}
body {
font-family: "Open Sans";
}
.collapse-link {
display: table;
color: #888;
text-decoration: none;
margin-bottom: 10px;
-webkit-touch-callout: none;
-webkit-user-select: none;
-khtml-user-select: none;
-moz-user-select: none;
-ms-user-select: none;
user-select: none;
}
.collapse-link:hover {
color: #000;
text-decoration: none;
cursor: pointer;
}
.collapse-link:after {
content: '\00276f';
display: inline-block;
}

.collapse-link-expanded {
display: table;
color: #888;
text-decoration: none;
margin-bottom: 10px;
-webkit-touch-callout: none;
-webkit-user-select: none;
-khtml-user-select: none;
-moz-user-select: none;
-ms-user-select: none;
user-select: none;
}
.collapse-link-expanded:hover {
color: #000;
text-decoration: none;
cursor: pointer;
}
.collapse-link-expanded:after {
content: '\00276f';
display: inline-block;
transform: rotate(90deg);
}
.collapsible {
display: none;
}
.collapsible-expanded {
display: block;
padding: 0px 20px 30px 20px;
}
</style>
<script>
function ToggleCollapsible(link, boxId) {
box = document.getElementById(boxId);
if (link.className == "collapse-link") {
link.className = "collapse-link-expanded";
}
else {
link.className = "collapse-link";
}
if (box.className == "collapsible") {
box.className = "collapsible-expanded";
}
else {
box.className = "collapsible";
}
}
</script>
</head>
<body>
<a class="collapse-link" onclick="ToggleCollapsible(this, 'options')">More Options      </a>
<div id="options" class="collapsible">
<ul>
<li><a href="#">Some Option</a></li>
<li><a href="#">Some Other Option</a></li>
</ul>
</div>
</body>
</html>
</source>

CSS Styles

2020-08-13T01:13:56Z

Beard: /* Collapsible Section */

== Apply CSS Based on Attribute ==

This just seems like less typing to me. Why type out class="something"? Especially in a wiki where you have to type it all the time.

CSS:
<source lang="css">
div[red] {
color: red;
}
div[blue] {
color: blue;
}
</source>

HTML:
<source lang="html">
<div red>
This should be red.
</div>
<div blue>
This should be blue.
</div>
</source>

RESULT:
<div class="box">
This should be red. 
This should be blue.
</div>

== Absolute Center (via Flexbox) ==

<syntaxhighlight lang="css">
.absolute-center {

/* Internet Explorer 10 */
display:-ms-flexbox;
-ms-flex-pack:center;
-ms-flex-align:center;

/* Firefox */
display:-moz-box;
-moz-box-pack:center;
-moz-box-align:center;

/* Safari, Opera, and Chrome */
display:-webkit-box;
-webkit-box-pack:center;
-webkit-box-align:center;

/* W3C */
display:box;
box-pack:center;
box-align:center;

}
</syntaxhighlight>

== Wrap Text in <pre> Tag ==

<syntaxhighlight lang="css">
/* wrap text in pre tag, good for mobile because pre won't extend beyond screen width */
pre.wrap {
white-space: pre-wrap; /* Since CSS 2.1 */
white-space: -moz-pre-wrap; /* Mozilla, since 1999 */
white-space: -pre-wrap; /* Opera 4-6 */
white-space: -o-pre-wrap; /* Opera 7 */
word-wrap: break-word; /* Internet Explorer 5.5+ */
}
</syntaxhighlight>

== Collapsible Section ==

<source lang="css">
<!DOCTYPE html>
<html>
<head>
<title>TEST 2</title>
<style>
@font-face {
font-family: 'Open Sans';
font-style: normal;
font-weight: 300;
src: local('Open Sans Light'), local('OpenSans-Light'), url(https://fonts.gstatic.com/s/opensans/v13/DXI1ORHCpsQm3Vp6mXoaTegdm0LZdjqr5-oayXSOefg.woff2) format('woff2');
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215, U+E0FF, U+EFFD, U+F000;
}
body {
font-family: "Open Sans";
}
.collapse-link {
display: table;
color: #888;
text-decoration: none;
margin-bottom: 10px;
-webkit-touch-callout: none;
-webkit-user-select: none;
-khtml-user-select: none;
-moz-user-select: none;
-ms-user-select: none;
user-select: none;
}
.collapse-link:hover {
color: #000;
text-decoration: none;
cursor: pointer;
}
.collapse-link:after {
content: '\00276f';
display: inline-block;
}

.collapse-link-expanded {
display: table;
color: #888;
text-decoration: none;
margin-bottom: 10px;
-webkit-touch-callout: none;
-webkit-user-select: none;
-khtml-user-select: none;
-moz-user-select: none;
-ms-user-select: none;
user-select: none;
}
.collapse-link-expanded:hover {
color: #000;
text-decoration: none;
cursor: pointer;
}
.collapse-link-expanded:after {
content: '\00276f';
display: inline-block;
transform: rotate(90deg);
}
.collapsible {
display: none;
}
.collapsible-expanded {
display: block;
padding: 0px 20px 30px 20px;
}
</style>
<script>
function ToggleCollapsible(link, boxId) {
box = document.getElementById(boxId);
if (link.className == "collapse-link") {
link.className = "collapse-link-expanded";
}
else {
link.className = "collapse-link";
}
if (box.className == "collapsible") {
box.className = "collapsible-expanded";
}
else {
box.className = "collapsible";
}
}
</script>
</head>
<body>
<a class="collapse-link" onclick="ToggleCollapsible(this, 'options')">More Options      </a>
<div id="options" class="collapsible">
<a href="#">Show Archived Items</a>
</div>
</body>
</html>
</source>