SManager Manual

By devwomdevwom, on 10 Jun 2012 10:19

Description

The main propose of Script Manager is execute shell scripts and executables in the easiest way, but if you are executing scripts, probably you will need a powerful root explorer and a powerful Terminal emulator, so the main line of Script Manager is:

Root file browser: Allowing manage your Android device file system
Terminal emulator: Where scripts and executables run.
Scripts and executables manager environment: Manage all selected scripts and executables, running them as root, on Network change, scheduled cron jobs, and a lot of options.

Browser screen

browser.png

Size

Text/icon size can be increased by configure it in config screen. No ads version also can modify size with Volume up/down keys.

Long tap options

Making long tap over file, you will get an options menu that allow:
Copy,Rename,Delete,Move and Share selected file
Also you can.,
Move to Home: Moves selected file/directory to selected directory as HOME in config screen.
Properties:Shows properties info of file.
Link: Creates a Symbolic Link to selected archive. Destination file system must accept symbolic links. Fat doest not accept them.
Open As: Allows open file as Script/executable, Text, Audio, Image or video.

Menu options

Home:Goes to HOME directory selected in config.
List: Opens List Screen
Favorites: Switch SManager to Favorites Mode
New: Allows to create new Directory and
New Script: To create new script, you can type the desired name or type sell-formed URL. If you insert URL, SManager automaticaly download such URL, and will propose new name.
Instead typing full name, you can capture it from QR code.
Console: Shows a list with all scripts running in SM Console, or create new Terminal emulator in SM Console. (No ads version, opens terminal in Browser's directory, ads version allways open terminal in HOME directory)
Advanced options:Opens Advanced Options selection dialog.
Filter: Shows filter box, in order to show in browser only files that match with such filter. Filter is not case sensitive.
Multiselect: Allows Multiselect files.
Help: Opens this help page
Close: Closes SManager.

Special Features

If you have select "Browse as Root" in Config Screen. When you select a file without write permission you will be asked about if you want create a copy of file in order to edit it and then replace file content. Or open it in view mode, so you can't modify it.

if the file does not have read permission SManager, automatically will create a coy and it will work with it. If it is modified, then you will be asked if you want save modified file as such file.

Favorites screen

favorites.png


In this mode you will browse along all scripts selected as favorites. As you can see, you could create folders in order to organize all your favorites scripts.
From this screen you can edit or run scripts selecting them.
Depending on "Single run on lists" selection in configuration when you select one script it will be executed or it will be opened Script configuration.
I you do not have selected "Single run on lists" you can run it with single touch by touching over RUN at the left of each script.
I you have selected "Single run on lists" you can edit Script configuration by long tap over script.

Menu options

List: Opens List Screen
Favorites: Switch SManager to Browser Mode.
Console: Shows a list with all scripts running in SM Console, or create new Terminal emulator in SM Console. (No ads version, opens terminal in Browser's directory, ads version allways open terminal in HOME directory)
Edit: Switch to edit mode, allowing organice your favorites scripts.
Help: Opens this help page
Advanced options:Opens Advanced Options selection dialog.

List screen

list.png


This screen shows all scripts configured in SManager and works similar to List Screen when you touch over script.
Also here you can filter your scripts by selecting below options. Filter options acts as OR.

SM Console

console.png

This is a Terminal emulator screen, where are send all foreground executed script and executables.
In this screen, you can also capture all scripts and executables launched in background via Widgets or shortcuts, or automatically launched from scheduled jobs.

Buttons

Kill/Close: Sends kill signal to showing script output or closes actual script execution tab if it has finished.
Font: Allows increase or decrease Terminal font.
AutoClose:If checked, it will NOT autoclose script's tab when script finished. It means that active script output will be autoclosed when you exit from SM Console if script has finished. That is, if you execute a script, automaticaly is shown SMConsole. After script finished you press back button, and script output will be removed from scripts tabs. This if for save your devices'memory. But under some situations, ma be you don't want autoclose scripts output after it has finished.
Light icon: ON=> script is working in wake lock mode. OFF => Wake lock is disabled for this script. If it does not appears you have disabled Wake lock in your configuration.
Tabs: Allows to switch between execution script or terminal emulators.

Gestures

Over Status bar, up slide to hide status bar. Or slide down from up screen to show status bar again. (Only no ads version)

Horizontal scroll gesture:
Top 1/3 of screen sends Home/End key events.
Middle 1/3 of screen sends Del/Tab key events
Below 1/3 of screen sends left/right key event.

Vertical scroll gesture:
Left 1/3 of screen sends up/down key event.
Middle 1/3 of screen sends page Up/page Down key event.
Right 1/3 of screen do nothing, i.e., standard console scrolling.

Keys

Some keys are also mapped to special keys:
Volume Up: Mapped to Esc key.
Volume Down: Mapped to Enter key.
DPad press: Mapped to Control key. (Press and then press other key. Not simultaneous pressing required)Menu options

Division line

Between status bar and console output, exist grey line that also shows Ctrl and Alt key status.
The most right side represent Control status key and the most left side represent Alt key.
Color map:
Grey: Not pressed.
Green: Pressed, the next one key press implies (Ctrl or Alt)+key
Red: Locked, all the next key press implies (Ctrl or Alt)+(pressed keys)

Consoles line

This is refered to the line that shows all running scripts.
If you dont see it, try press left green button to unhide it.

Menu Options

Run Again: Executes again same script. Only enabled when script has finish.
Share: Shares script output. Only enabled when script has finish.
Tog. Status: Toggles status bar visibility.
Console: Shows a list with all scripts running in SM Console, or create new Terminal emulator in SM Console. (Opens terminal in HOME directory)
Edit: Switch to edit mode, allowing organice your favorites scripts.
Help: Shows quick help about SMConsole.
Exit:Closes SM Console and returns to Browser Mode or Favorites Mode.
If active script has finished and autoclose is checked, automatically will be removed from all opened consoles. If autoclose is not checked it will remain in opened consoles.
If active script is not checked, you will be asked about:
Kill: Kills active script and exits.
Leave in background: Leave script running in background.
Cancel: Returns to SM Console.

SM Editor (Root editor)

IMPORTANT: SM Editor always open files in root mode, that is, regardless file permission, you can edit it and then modify its content, so use it carefully.

It is a basic editor to allow make little changes in your preferred scripts.

You also can insert code from QR codes and share it vie email.

Advanced Options

Menu advanced options has following options:

Config: Opens Config Screen.

View Logs: Allow view all logs registered by SManager for all scripts executed in background, like onBoot, onNetwork, scheduled jobs and background Widgets and shortcuts.

Scheduler: Opens Scheduler screen in order to set scheduled cron jobs.

Mount /system: Mount /system folder as read only or read and write mode. You device must be rooted and selected "Browse as root" in Config Screen.

Migrate data: Allows copy data from Ads version/No ads version. Only copies all configured scripts and scheduled data. Configuration must be reset again.

Uninstall SMWidgets: Allow uninstall SMWiget add-on.

Script configuration

TODO

Multiselect

TODO

Scheduler screen

IMPORTANT: It is highly recommended "Enable Wakelock" in config if you use scheduled jobs. Why? please read WAKE_LOCK permission.

Main screen
In this screen you can add new scheduled jobs.

SchedulesList.png

Also shows all configured scheduled jobs, and them configuration.
And you can enable or disable each of it by pressing On/Off button.
By pressing on each job, or adding new timer, you will can configure the new job in Configuration Screen.

Configuration Screen

ScheduleInfo.png

In this screen you can configure the job, adding script (will be selected from your configured scripts). Or adding file, if you do not have configure it in SManager.

I you want change schedule job, you need touch Name tag.
To configure schedule execution time, touch over Repeat tag.

After any modification, you must press save button in order the job be saved.

Monthly Configuration

ScheduleMonthConfig.png

In this screen you can configure scripts that are executed once at month.
Day to run goes from 1 to 28.
Touch over Time tag in order to configure execution hour.
You also can select the months in which you want execute the job.

Weekly Configuration

ScheduleWeekConfig.png

This screen allow configure script to execute daily, you can check the days that job must be executed.

Run each: Means, de execution period, in hours:minutes, between Time and Until configured hours. If you select 00:00 the job will be executed only once at a day at configured Time.

Time: Touching over Time tag, you can modify start executing time or execution time (in case once jobs). The day starts at 00:00 hours minute.

Until: time, is valid only to periodic jobs (Run each value distinct of 00:00), refers when they will stop running until next selected day. For once jobs it is disabled. Note that the last Until hour:minute is 00:00.

Config Screen

TODO

Foreground/Background Scripts

In SManager scripts can run scripts in foreground or in background.

Foreground scripts are scripts that when launched opens SMConsole.

Foreground scripts always be present in SM Console, so always can follow them execution.

Background scripts are scripts that executed without opening SMConsole. These scripts are scripts marked to run on boot, on network, etc. Also scripts that are inside scheduled job, are background scripts when schedule is executed. That is, all script that are executed automatically, without user request. In SManager no ads version, widgets that have been selected as run in background also are background script.

Background scripts, does not need SMConsole to run, because them run in background. But they virtually run in SMConsole. This mean that if you have SMConsole open you will see how they appear and disappear (when finish) in Consoles line.

Also, when background script has finish, its output is logged, and you can read its output and it exit code Viewing logs.

So if you want follow a script execution, for foreground scripts you only need don't close SMConsole :-).

For background scripts, if it is running, you need open SMConsole and locate it in Consoles line. If you don't see Consoles line, press left green arrow to see all executing scripts.

If your background script is not in Consoles line, is because it have not been executed, or because it has finished, and it is on logs

Permissions

android.permission.WAKE_LOCK
As Android devices, suspend CPU when it suspend device (when screen is off) in order to save battery, this permission is needed to make sure the CPU will not be stopped while scripts are executing.
SManager acquires PARTIAL_WAKE_LOCK PowerManager.WakeLock when scheduled jobs are executed, onBoot and onNetwork scripts and when background scripts are launched from Widgets or shortcuts. Also you can force to a script to take this wakelock by checking Enable Wakelock in options of each script.

If you don't check "Enable wakelock" in configuration options, SManager NEVER will use this permission, so when your screen goes black, the script will be stopped. This causes malfuction in some scripts.

Scripts variables

SM_ALIAS
Alias of script executed

SM_GUIFD
GUI file descriptor. To show graphical dialogs.

SM_HOME
Default home directory configured

SM_LAUNCHER
Action that executed the script. Possible values:

MANUAL: User executed the script.

ONBOOT: Script was executed due cellular boot.

ONNETWORK: Script was executed due network connection change.

ONBLUETOOTH: Script was executed due bluetooth event. Available from SManager 2.7.0 version.

SM_NET_*

The following variables only are available when SM_LAUNCHER is equals to ONNETWORK. And its values are directly wrapped from NetworkInfo class

SM_NET_AVAILABLE
Possible values 1/0 => true or false

SM_NET_CONNECTED
Possible values 1/0 => true or false

SM_NET_FAILOVER
Possible values 1/0 => true or false

SM_NET_REASON
Empty or method returned value

SM_NET_ROAMING
Possible values 1/0 => true or false

SM_NET_SUBTYPE
Method returned value

SM_NET_TYPE
Method returned value

SM_BTH_*

The following variables only are available when SM_LAUNCHER is equals to ONBLUETOOTH (Available from SManager 2.7.0 version.). And its values are directly wrapped from BluetoothDevice, BluetoothClass depending on Bluetooth action received

SM_BTH_ACTION
Possible values:
android.bluetooth.device.action.ACL_CONNECTED
android.bluetooth.device.action.ACL_DISCONNECTED
android.bluetooth.device.action.ACL_DISCONNECT_REQUESTED
android.bluetooth.device.action.BOND_STATE_CHANGED
android.bluetooth.device.action.CLASS_CHANGED
android.bluetooth.device.action.FOUND
android.bluetooth.device.action.NAME_CHANGED

SM_BTH_ADDRESS

SM_BTH_NAME

SM_BTH_BOND_STATE

SM_BTH_CLASS

SM_BTH_DEVICE_CLASS

SM_BTH_EXTRA_BOND_STATE

SM_BTH_EXTRA_PREVIOUS_BOND_STATE

SM_BTH_EXTRA_NAME

SM_BTH_EXTRA_RSSI

SM_VERSION
Script Manager version name.

SM_VERSIONCODE
Script Manager version code.

GUI Interface:

Script Manager implements the possibility to show a few dialogs in graphic mode from shell scripts.
It is possible, writing to the special file descriptor stored in SM_GUIFD variable.

Protocol:

Script Manager implements a simple protocol to show dialogs.
It consist writing a line (ie, ends with New line) to SM_GUIFD file descriptor. When SManager reads this line, it process data and writes as return the selected data in dialog.

Each command line is as follows:
<action> [<argument> …]

Where action is the dialog type to show, and argument/s are the required arguments for that action.
Arguments can has spaces if they are enclosed between double quotes.

For example, if you want to show a yes/no dialog you must write in you script the following command.

echo showYesNoDialog "Dialog title" "Please select yes or no message" >&$SM_GUIFD

And to read selected value you must write

read res <&$SM_GUIFD

and in $res you will have selected value.

Implemented dialogs

showToastShort
Shows a Toast with short time.

Arguments: Desired message to show
Return value: none

showToastLong
Shows a Toast with long time.

Arguments: Desired message to show
Return value: none

showYesNoDialog
Shows a yes/no dialog.

Arguments:
Number of allowed arguments 1 or 2
1 argument => only shows message
2 arguments => first argument title. Second argument is the message

Return value: y , n or empty string if the dialog was cancelled.

showOkDialog
Available from SManager 2.7.0 version

Shows a dialog only with Ok button.
IMPORTANT: when Ok is pressed, new line is written to SM_GUIFD stream, so always is needed read from it
Example always add these two lines

echo showOkDialog \"This is my title\" \"This is my message\" >&$SM_GUIFD
read res <&$SM_GUIFD

Arguments:
Number of allowed arguments 1 or 2
1 argument => only shows message
2 arguments => first argument title. Second argument is the message

Return value: y , n or empty string if the dialog was cancelled.

showInputDialog and showInputPasswordDialog
Shows an input box dialog. if action is showInputPasswordDialog the typed text will be hidden.

Arguments:
Optional arguments [ -d "default_value" ] adds default value for Input field, not requiring 4 arguments. Available from SManager 2.7.0 version

Number of allowed arguments 1, 2, 3 or 4
1 argument
only shows message
2 arguments
first argument title
Second argument message
3 arguments
first argument title.
Second argument message.
Third argument hint text
4 arguments
first argument title.
Second argument message.
Third argument hint text
Fourth default text
return value: typed string or empty string if dialog was cancelled

showSpinnerDialog (single select option)
Shows a dialog with an array of options. Only is possible select one option.

Arguments:
Optional arguments [ -s "default_selection_index" ] set as checked default_selection_index item, starting at 1. Available from SManager 2.7.0 version

Number or arguments 2 or more
First argument: title
Rest of arguments: options
return value: selected index option. (First option is 1)
Empty string if dialog was cancelled

showSpinnerMultiselectDialog (multiple select option)
Shows a dialog with an array of options. It is possible select multiple options.

Arguments:
Optional arguments [ -s "default_selection_index" ] [ -s "default_selection_index" ] …
Set checked default_selection_indexes item or items, starting at 1. Available from SManager 2.7.0 version

Number or arguments 2 or more
First argument: title
Rest of arguments: options
return value: space separate selected options. (First option is 1)
Empty string for no selections or cancelled dialog.

Example

You can download the following script that creates a ssh backup.
samplebackupqr.png

smc Commands:

Since SManager Version 2.8.0 it is available smc command, this adds more functionality to the scripts running inside SManager.
It works in similar way than busybox, that is:
smc command [arguments …]

NOTE: Do not call smc in background, ie, don use
smc command [arguments …] &
like commands

smc File management
smc Play File

smc file management [BETA STATUS]

The smc file management commands implement basic file operations for files that can manage SManager, that is, copy files from inside zip files, copy,move,delete files and create directories in dropbox,boxnet, ssh servers, etc using SManager add-ons
Ie, allow the possibility to modify network files from your scripts.
cp command: accepts -r flag
mv command: does not accept flags
rm command: accepts -r flag
mkdir command: does not accept flags

NOTE:Unfortunately these commands can not be used in background scripts(scheduled,events or background shortcuts) since sometimes they need user interaction, like requesting passwords and overwrite dialogs

smc file management schemes

smc file management uses uri as origin and destination files, for network files and for local files

Local files

In order to refer to your device local files you need to use the following uri format

file:///path/to/file

note 3 slash between scheme and the path

Boxnet files

In order to refer to your Boxnet files you need to use the following uri format

boxnet://ten.niamod|liamresu#ten.niamod|liamresu/path/to/file

Where ten.niamod|liamresu#ten.niamod|liamresu is your user mail at boxnet account

Dropbox files

In order to refer to your Dropbox files you need to use the following uri format

boxnet://userid/path/to/file

Where userid is your userid at dropbox account. You can get your userid from your SManager configured connections

Windows/samba, sftp/ssh ftp files

In order to refer to your Windows/samba, sftp/ssh ftp files you need to use the following uri format

shceme://user@host:port/path/to/file

Where scheme is
smb: for Windows/Samba connections
sftp: for sftp/ssh connections
ftp: for ftp connections

user@ and :port are optional

Packed files

Packed filer refers to file tree that resides inside a single file like compressed files.
NOTE: Packed files are read only files
At this moment SManager supports following schemes for packed files.
zip: browse inside zip/apk and jar files
yaffs2: browse inside basic yaffs2 disk images
tar: browse inside tar files
tgz: browse inside gzip tar compressed files
tbz2: browse inside bzip2 tar compressed files

In order to refer to packed files you need to use the following uri format
scheme:REALFILE!//path/to/file

Where scheme is zip,yaffs2,tar,tgz or tbz
and REALFILE is a real packed uri, including packed files

For example
zip:file:///path/myfile.zip!//path/inside/zip/log.txt
Refers to file /path/inside/zip/log.txt inside /path/myfile.zip in your device file

tgz:sftp://user@myserver/path/myfile.tgz!//path/inside/tgz/to/directory/
Refers to /path/inside/tgz/to/directory/ inside /path/myfile.tgz file stored in myserver host using user user

NOTE: Packed directories always must end on slash character(/)

Some examples

smc cp -a "dropbox://numeric_user_id/Photos" "file:///sdcard/photos_dropbox"

smc cp -r sftp://user@host:3567/home/user/kk/*a* file:///sdcard/kk/k2

smc mkdir "boxnet://user@domain.net/onefolder" && smc mv "boxnet://user@domain.net/onefolder" "boxnet://user@domain.net/newname"

smc cp "file:///ueventd.mako.rc" "boxnet://user@domain.net/newname/"

smc rm -r "boxnet://user@domain.net/newname"

smc cp -r "ftp://user@ip_dir/home/user/one/directory" file:///sdcard/one/file "boxnet://user@domain.net/newname" smb://guest@other_ip/other/dir sftp://user@mymachine/home/user/destdir/

smc cp -r zip:dropbox://user_id/zipfile.zip!//directory/* sftp://user@host:1234/home/user/directory/

smc play file

In order to play file inside a script you can use the following command
smc playFile [-bg] /path/to/file
If you use -bg flag, the file will be played in background, and did not stop script until play is finished.
NOTE:You can use it in background scripts

Examples:
smc playFile -bg /sdcard/toy_mono.wav
smc playFile /system/media/audio/ui/Undock.ogg

smc Return code

As usual smc exit code is 0 on successful complete command and !=0 on error

Intents:

Following intents are accesible for externals applications.

Open SManager Browser at desired directory:

Intent intent = new Intent(Intent.ACTION_VIEW,Uri.parse("file://"+directory));
startActivity(Intent.createChooser(intent,this.getString(R.string.browsewith)));

Or if you prefer start it from command line (adb)
am start -a android.intent.action.VIEW -d file:///data/

Execute script from other application:

String action;
if(noAdsVersionInstalled)
action="os.tools.scriptmanagerpro.action.LAUNCH_SCRIPT";
else
action="os.tools.scriptmanager.action.LAUNCH_SCRIPT";

Intent intent = new Intent(action);
intent.setData(Uri.parse("file://"+SCRIPTNAME));
intent.putExtra("RUN_AS_ROOT_EXTRA", true);//Is optional

Or if you prefer start it from command line (adb)
am start -a os.tools.scriptmanager.action.LAUNCH_SCRIPT -d file:///data/myscript.sh --ez RUN_AS_ROOT_EXTRA true

RUN_AS_ROOT_EXTRA: is optional

Known Issues

Background commands in scripts are not executed.

Really they are executed, but if the script finish, before background commands are fully executed, the background commands are not correctly executed.
Add a wait command as last script line in order to wait all commands finish.

FAQ's

Why I cant browse system files?

First of all, your device must be rooted, if not is not possible.

By default SManager does not enables browse as root in order to prevent modify undesired files. You need check it in configuration. menu->more->Advanced Options->Config->Browse as root.

exec: sh: not found or some executables are not found:

Check how did you have override PATH variable in config. If it is not overridden this is not the issue.

Market says my device is incompatible:

New market has some restrictions with lcd density. http://forum.xda-developers.com/showthread.php?t=1333584.

You can get SManager here.

I've purchased Pro version but Android Google Play rejects license:

There are some issues that can be involved.

Device date time

  • So, check your device date time.

Google Play missed configuration

  • 1) Start the “Settings” app.
  • 2) Tap “Applications”, “Manage applications”, “All”, “Google Play Store”, “Clear cache”
  • 3) Restart SManager Pro
  • If does not work, you can check hard mode
  • 1) Uninstall SManager Pro
  • 2) Reboot device
  • 3) Clear Android Play market data and cache as above
  • 4) Reboot device
  • 5) Install SManager Pro
  • 6) open SManager Pro ensuring device is connected to the internet.

":not found" and ": no such file or directory" execution errors:

This is a well know and common error in scripts that are write in windows environments and executed in linux (like android).
The reason is the end of line (EOL) in text files.

Linux scripts have issues if they have "CR+LF" EOL.
They should have "LF" EOL.

So using a text editor that allows use LF EOL is recommended.
One of them is Scite text editor
And another one is Notepad++
Also it is possible use SMEditor, but it could be tedious for big scripts.

Obviously you can use other editors, but make sure they have LF EOL.

Are the background script executed in parallel or sequentially?

The background scripts are executed in sequential mode. They are executed in case INsensitive based on their alias name.

Why can not be executed scripts as background process and how to run them as background processs?

In android OS, applications running in background and services, can be killed when device's ram is low, that is they if you open 20 Apps, probably the first opened app is not running.
Really Android OS have service mode application that usually they are not killed while service(scripts in background) is running, but note "usually", so what happens if the service is stopped?? This is why SManager at this moment does not support scripts as background processes.

Afortunatelly a script can be easilly convert to daemon using nohup command.
You can execute a script from another script as daemon as follows

sh -c "nohup /sdcard/daemon.sh 0<&- &>/dev/null &"

if you do not want use 2 scripts you can put the script itself as daemon as follows

#!/system/bin/sh
if [ -z "$DAEMONIZED_FLAG" ] ; then
    sh -c "DAEMONIZED_FLAG=1 nohup \"$0\" 0<&- &>/dev/null &"
    exit
    # use 
    # sh -c "DAEMONIZED_FLAG=1 nohup sh \"$0\" 0<&- &>/dev/null &"
    # if script is stored under /sdcard/
    # NOTE: sh after nohup
fi
#here start script code
scp bigfile user@192.168.0.2:/home/user/backupfiles/bigfile

NOTE: you can redirect the script output to your prefered file using &>/sdcard/outscript instead &>/dev/null

Add a New Comment
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License