Apcupsd UPS control software Files

     apcaccess for Android

This program is an experimental precursor program to writing a
full Android GUI apcaccess application.  PLEASE send feedback
to the mailing list, that will help to see if there's interest
in further pursuing it.  It's also a good introduction
to using console mode programs on Android.


In this directory you will find the following files:

apcaccess  -  For Android 3 (maybe) 4.1 and later
apcaccess.nopie  -  For Android 2.3, 3 & 4 but not 5
libapc.a   -  For Android 3 (maybe) 4.1 and later
libapc.a.pie  -  For Android 2.3, 3 & 4 but not 5

These files were compiled on a Ubuntu 12 system using version
10d of the Android NDK (Native Development Kit) and targeting the
ARM cpu and the Android 9 architecture.  The apcaccess programs
have been tested on Android version 4.4.2 and version 2.3.6
Smartphones and an Android version 4.1.1 Tablet.  Test both the
Position Independent Executable and the non-PIE executable on your
Android device and delete the one that segfaults and rename the one
that works to apcaccess.  And PLEASE post to the apcupsd mailing
list what device you used this on and what binary you used it on.

If you have an Android device that is running an
Intel CPU or MIPS device then please post to the apcupsd
mailing list asking for a build.  I do not have Android devices
with those CPUs so I cannot do any testing that is why I have
not included builds for these CPUs. The same goes for an
Android 2.2 or earlier device.  Note that with Android version
5.0 and later (Lollipop), applications must be compiled as PIE.

The apcaccess binary is statically linked so there is no need
to copy the library over to your android device to run the
apcaccess program.  These libraries are included in this tarfile
in case someone wants to build an apcaccess GUI application for Android.

Note that this program has NOT been taken through the process to
build an .apk file for it because it is a command line program
and therefore must be run at the Android command line.  The .apk
file carries defines of what devices programs can run on so
Google Play Store does not display programs your device cannot
run.  With Android command line programs it is expected that
the user can deal with this.

ANDROID SECURITY AND COMMAND LINE PROGRAMS

With Android version 4.3 and later, AndroidOS removed the
ability to run setuid and setgid programs.  This affects programs
like ping (which needs access to raw sockets).  apcaccess uses
standard TCP packets and so does not need to run setuid.

Android OS also does not allow files to have the execute bit
set unless they are in the Android app data area.  If your phone
or tablet has a removable SD card you cannot copy a file to it
and set the file executable.

Finally, Android has much of the filesystem set read-only.  When
programs run they are run as a unique user and only have write access
to very limited areas of the filesystem.

As a result of this a user who wants to run command line Android
programs has to either root their device or use some tricks to
run programs that don't require root access.

In general, rooting on Android devices is done either through
a security escalation in a software bug in a stock rom, or
by replacing the rom firmware of the device with a rom image that
has been compiled with root access.

If you want to root then be aware of a few things. Smartphones
and Tablets that were supplied from cell carriers and MVNOs are
not going to be easy (or possible) to root.  Tablets which are
wireless (not from a cell carrier) are going to be easier to
root, and Smartphones supplied from manufacturers as "developer"
phones will be easiest to unlock and root.

Note that the current direction that Google is heading is towards
pushing device manufactures to ship Android devices with locked
bootloaders.  The bootloaders can only be unlocked by "blowing"
special hardware fuses.  As a result if you root your phone by
unlocking the bootloader and loading a rooted firmware on it, the
manufacturer will be able to tell if you send the phone in for
a warranty fix, even if you unroot it and flash it back to stock.
That is why it is worth paying the premium for Developer smartphones
as they will still honor warranty if you unlock their bootloaders.

Note also that network unlocking a smartphone is not the same thing
as bootloader unlocking it.


INSTALLATION PREFACE

If you have not yet installed or used console mode command line
programs on your Android device you might want to read this section.

The installation instructions here are a distillation of the
procedure detailed here:

http://kevinboone.net/android_nonroot.html

You may want to read through that if you are interested in further
exploring command line utilities on Android.

Next, while it is not required, you may want to install
BusyBox.  If your device is rooted you likely already have it installed,
if your device is not rooted here is a guide to use to install it:

http://kevinboone.net/android_nonroot.html

Busybox helps you to not have to use hacks like "cat file > file"
to do simple things like moving a file around.  But, it isn't 
required for this apcaccess program.


INSTALLATION:

The first step is installing an Android terminal emulator
program.  A good one is "Terminal Emulator" by Jack Palevich
it is free from the Google Play Store.

The next step is copying the 2 binary programs of apcaccess
to the Android device.  You can put them on a website then
copy them down using Chrome - although Chrome will usually
rename them to .bin files.  Firefox will also download them
but it won't rename them.  Or you can plug in a USB cable
and copy them over to /sdcard/DCIM/Camera but make sure to
delete them once you have put them in position.

Browsers under Android generally put files
that are downloaded into the /sdcard/Download directory. (even
Android devices without a separate SD memory card will have this
directory)


ROOTED DEVICES

If your rooted you can then open your terminal emulator,
su to root, then create a local binary directory and copy
apcaccess to it, and rename it.  You will likely have BusyBox
on your phone and will likely have ES Filemanager or other
filemanger that requires root.

NON-ROOTED DEVICES

You can still run apcaccess but your going to have to use a trick
to do it.  Android does not allow users to set the execute bit
on files that are on the SD card.  Executable files must be located
in the app storage area.  However, console utilities like apcaccess
that are not bundled in an .apk file won't be installed in the Android
system.  That's where our Terminal Emulator comes into play.  Android
installs these apps into the app data area and so when you run Terminal
Emulator, everything in the filesystem that is in Terminal Emulator's
install directory data/data/jackpal.androidterm/ will be writable
by the Terminal Emulator process.

We can put our command line programs in there and run them.

Note that older Android devices may not have the cp utility but
we can use cat in place of it.  Here are the steps:

1) Run the Terminal Emulator on the Android device
2) In the Emulator:

cd /data/data/jackpal.androidterm/shared_prefs

This directory may be different if you install a different Terminal
Emulator program, but there WILL be a directory on Android that
is writable by that program.

cp /sdcard/Download/apcaccess.bin .
or
cat /sdcard/Download/apcaccess.bin > apcaccess

You cannot mv (move) a file in Android from one filesystem to
another, you have to copy it then remove the source file.  And you
likely won't have the cp program on older Android devices that
have an older toolbox binary.

Busybox has a cp command (and many better ones than what are
supplied in the stock toolbox binary) 

The source apcaccess file may be apcaccess or apcaccess.bin or
apcaccess.nopie or apcaccess.nopie.bin depending on how you downloaded
the file to the phone.

Set the program executable by:

chmod 755 apcaccess

Now the apcaccess program is installed on your Android device and can
be run from the Terminal Emulator program just like on any Unix system,
for example:

./apcaccess status remotehostwithapcupadrunningonit

The output from your UPS will be displayed.  Note the terminal emulator
program has the ability to modify the path so you can add appcaccess to
the path if you want.  See:

https://github.com/jackpal/Android-Terminal-Emulator/wiki

NOTE:  Your server must make port 3551 accessible to the network that
your phone or tablet is using.

Ted Mittelstaedt
http://www.mittelstaedt.us (links there to various "real" websites you can
contact me on ;-)