Blue Iris Tools Add-ons

Blue Iris Tools Add-ons

This wiki article will outline what the Blue Iris Tools Add-ons feature does, how it works and how to use it. The BIT Add-ons was developed in response to a member requesting certain weather results be modified after they are gathered. This gave me the idea to create the add-ons feature which will allow users to build their own add-ons to interact with BIT and Blue Iris.

How Add-ons Work

Blue Iris Tools has been assigned a bunch of event handlers which are routines / triggers that are executed in response to an event or action in BIT or BI. The add-on system system allows you to assign particular files (such as .bat files, .exe files, scripts, etc.) to different event handlers, so when the particular event handler is triggered, the file assigned to it will be executed.

All event handlers (except the individual weather functions (Ex: temp, humidity, etc.)) are executed at the end of the Blue Iris function. For example, the "weather_get" handler is triggered at the end of the weather retrieval process. In other words, after BIT has finished gathering all the weather data, then the event handler is triggered. Another example is the "program_load" handler is triggered at the end of the BIT loading process, after all values and settings are loaded. This is designed to help keep BIT running even if the scripts have issues. Keep in mind, bad scripts or improperly executed (admin rights, normal state, etc) can still cause BIT to slow down or even stall so make sure you set everything properly.

How To Create BIT Add-ons

The add-ons system is built on an event handler / trigger method which executes certain files / scripts. Blue Iris Tools (v1.3.0 +) has Event Handlers throughout the software which are triggered during certain activities, which in turn execute files.

Step One - Name The Folder

The first step in creating a Blue Iris Tools add-on is to define a folder name for the add-on. The folder name can be anything (as long as the characters are allowed in the name) and does not have to match the add-on name. However, once the add-on is created or saved you should not edit the folder name. Input a name for the folder then click the "Create" button.

Step Two - Add-on Details

After you name and create the folder, the next screen will be the "Add-on Maker". The next thing you should do is fill out all of the information about the add-on. The add-on name will automatically be filled out as the folder name but you can change it to whatever you want. If you are a member of IP Cam Talk (which if you're not, you should be ) then the "Author" section is your IPCT username and the "IPCT Member #" is your member #. You can get your number from the URL of your profile, it's the last # on it. Ex: My member number (@Mike) is 2 and the url is https://ipcamtalk.com/members/mike.2/ Since all add-ons are hosted in our Downloads section you do not need to input the first part of the url, only everything after /downloads/. Same with the thread url, only input the 2nd half. Threads are automatically created in the Blue Iris Add-ons section after an add-on is uploaded to the Downloads section. Note: Clicking the "Release Date" & "Version Date" labels will set the value to today's date. Clicking "Path" will open the path.

Step Three - Adding Files

The next step is adding files to the the add-on. The files are what will be executed / launched at the specified event handler. Click the "Add File" button to select a file to add. Note: Files must be in the specific add-on folder (subfolders within the folder are fine). You can easily move the file to the add-on folder by clicking "Copy file to...". Select the file that you would like to add to the add-on, then click "Add file to add-on"

(This image shows the screen after clicking "Add File")

This part is important so pay attention. After adding a file to the add-on you will be prompted with a message and brought back to the "Add-on Maker" screen. The next thing to do is assign handlers to the file or cancel the assigning process. You cannot do anything else until you select an event handler(s) and assign it to the file, OR "Cancel Adding Handlers to Selected Files".

Assigning Event Handlers to Files

Files are executed at certain BIT event handlers. To assign event handlers to files you first must have a file in the add-on, and that file must be selected. One the file is selected (or immediately after adding a file to the add-on), select one or more handler on the left side, then click "Add Handler to Selected File".

Again, immediately after adding a file you cannot do anything else until you add a handler(s) or cancel the adding process.

You will see the handler in the list of handlers on the right after adding it to the file.

Step Four - File Properties

After adding the event handlers to your file you should select how you want the file to be executed. The "State" property is the window state of the file. "Normal" means it will be opened and focused on like a normal program / script. The majority of the time you will want this to be "Hidden" so that the file is executed in the background as opposed to being open and visible in the foreground.

The "Run as Admin" property will either execute the file with administrator privileges or without.

Step Five - Enable Add-on

Repeat steps 3 and 4 for any files you would like to add and for all handlers you would like associated with each file. Once you are done adding files and configuring handlers your add-on is ready for use. There is no save button because add-ons are saved on the fly. To enable your add-on click the "Installed Add-ons" tab, then the "Refresh List" button. If you don't push this button your newly created add-on will not appear. Once your add-on list is refreshed, click your newly created add-on, then check "Enabled" near "Status" on the top right. Once an add-on is enabled it will be executed at the various event handlers and you're all set!

Execution Order

Execution order may be important for certain add-ons or files. An example of when it would be important is if an add-on runs multiple scripts that need to be executed in order. BIT Add-ons allows you to specify the order of execution for both files and handlers.

Add-on Execution Order

Add-ons are executed in the order that they are listed in the "Enabled Add-ons" list. You can change the execution order by moving add-ons up and down on the list

File Execution Order

File order can matter and just like add-ons, files are executed in order and can be moved up and down on the list.

Event Handlers

Below is a list of event handlers that add-ons can trigger. Event handlers are predefined in BIT and can easily be added to your add-ons via the add-on maker. You can assign as many event handlers as you want to as many files as you want, but make sure to have a complete understanding of when they are triggered as some event handlers will be triggered at the same time, such as "watchdog_trigger_any" and any other "watchdog_trigger" handler.

CPU

CPU handlers are triggered at defined CPU ranges. The CPU Watchdog must be active for any of these handlers to work. All of these are self-explanatory by the name and will be triggered at certain CPU range levels.

• cpu_between_01_09

• cpu_between_10_19

• cpu_between_20_29

• cpu_between_30_39

• cpu_between_40_49

• cpu_between_50_59

• cpu_between_60_69

• cpu_between_70_79

• cpu_between_80_89

• cpu_between_90_100

Weather

Weather handlers are triggered during BIT's weather gathering.

• weather_error

  When BIT errors during the weather process. Can be due to a bad weather station ID, etc.

• weather_get

  At the end of the weather gathering process of BIT

• weather_get_dewpoint

  Dew Point gathered

• weather_get_heatindex

  Heat Index gathered

• weather_get_humidity

  Humidity gathered

• weather_get_precipitation

  Precipitation gathered

• weather_get_precipitationrate

  Precipitation Rate gathered

• weather_get_pressure

  Pressure gathered

• weather_get_solar

  Solar Radiation gathered

• weather_get_temp

  Temperature gathered

• weather_get_uv

  UV gathered gathered

• weather_get_windchill

  Wind Chill gathered

• weather_get_winddir

  Wind Dir gathered *Updated 1/18/20 due to WU changes

• weather_get_windspeed

  Wind Speed gathered

• weather_retry

  When BIT is unable to gather the weather but does not error and retries

Program

Program handlers have to do with the BIT and Blue Iris programs.

• program_backup_bit

  BIT is backed up

• program_bi_updated

  After Blue Iris (not BIT) is updated

• program_cloud_inbound_connected

  Incoming BIT Cloud connection is successful

• program_cloud_inbound_disconnected

  BIT Cloud connection disconnected

• program_exit

  BIT exits

• program_error

  Any error on BIT (Currently about 75% of errors are handled)

• program_load

  BIT loads

• program_log_write

  Log entry is written

• program_minimize

  Program is minimized

• program_restore

  Program is restored from being minimized

• program_updated

  After BIT is updated (on the first load of the new version)

Watchdog

Watchdog handlers are triggered by certain Watchdog functions.

• watchdog_alert_close_before_opening

  Watchdog is triggered and the "Close BI before opening it" option is selected. Triggered after BI is closed then opened

• watchdog_alert_email

  Watchdog triggers an email. Handler is triggered regardless of email success or failure

• watchdog_alert_pushover

  After a Pushover notification is sent

• watchdog_alert_sound

  After a sound is played

• watchdog_alert_url

  After a URL is launched

• watchdog_freeze_screen

  If BI is detected as being frozen

• watchdog_ip_change

  IP address changes - DDNS Watchdog must be enabled

• watchdog_max_alerts

  Maximum Watchdog alerts per hour are reached

• watchdog_trigger_any

  Any Watchdog is trigger (Program, CPU, DDNS, etc.)

• watchdog_trigger_cloud

  BIT Cloud Watchdog is triggered

• watchdog_trigger_cpu

  CPU triggered

• watchdog_trigger_ddns

  DDNS triggered

• watchdog_trigger_program

  Program triggered

• watchdog_trigger_webserver

  Webserver triggered

• watchdog_update_manager_trigger

  Update manager triggered. Handler is triggered after the update is backed up.

Basic Add-on Tips To Remember

There are some key things to remember when developing and using add-ons. Here is a basic list of things to keep in mind.

• The add-on system is globally enabled by checking "Enable Add-on System". If this is disabled then no add-on will be executed.
• Each add-on is enabled or disabled by checking the "Enabled" option in each particular add-on.
• Make sure you are conscious of state and "Run as Admin" options for each file. Some scripts may need to be run as admin and some may not function properly if they are. The state determines what window state the file will be executed in. Most of the time you would select hidden so that you don't have a bunch of windows open on your PC.
• Add-ons are stored in the /addons/ folder in your BIT directory.
• Add-ons are not actually deleted when you press "Trash Add-on", rather moved to the "/addons/addons_trash/" folder. To restore add-ons simply move them back into /addons/.
• Add-ons can cause BIT to slow down and in some cases stall. Please make sure the script you are executing does not have errors and will execute properly.
• A lot of the event handlers have not been tested, if you find any issues please contact @Mike