Blue Iris Tools Add-ons
- Blue Iris Tools Add-ons
- How Add-ons Work
- How To Create BIT Add-ons
- Step One - Name The Folder
- Step Two - Add-on Details
- Step Three - Adding Files
- Assigning Event Handlers to Files
- Step Four - File Properties
- Step Five - Enable Add-on
- Execution Order
- Add-on Execution Order
- File Execution Order
- Event Handlers
- Basic Add-on Tips To Remember
Blue Iris Tools Add-ons(top)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(top)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(top)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(top)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(top)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(top)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(top)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(top)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(top)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(top)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(top)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(top)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(top)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(top)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.
Weather(top)Weather handlers are triggered during BIT's weather gathering.
weather_error(top)When BIT errors during the weather process. Can be due to a bad weather station ID, etc.
weather_get(top)At the end of the weather gathering process of BIT
weather_get_uv(top)UV gathered gathered
weather_get_winddesc(top)Wind Description gathered
weather_get_windchill(top)Wind Chill gathered
weather_get_windspeed(top)Wind Speed gathered
weather_retry(top)When BIT is unable to gather the weather but does not error and retries
Program(top)Program handlers have to do with the BIT and Blue Iris programs.
program_backup_bit(top)BIT is backed up
program_bi_updated(top)After Blue Iris (not BIT) is updated
program_cloud_inbound_connected(top)Incoming BIT Cloud connection is successful
program_cloud_inbound_disconnected(top)BIT Cloud connection disconnected
program_error(top)Any error on BIT (Currently about 75% of errors are handled)
program_log_write(top)Log entry is written
program_minimize(top)Program is minimized
program_restore(top)Program is restored from being minimized
program_updated(top)After BIT is updated (on the first load of the new version)
Watchdog(top)Watchdog handlers are triggered by certain Watchdog functions.
watchdog_alert_close_before_opening(top)Watchdog is triggered and the "Close BI before opening it" option is selected. Triggered after BI is closed then opened
watchdog_alert_email(top)Watchdog triggers an email. Handler is triggered regardless of email success or failure
watchdog_alert_pushover(top)After a Pushover notification is sent
watchdog_alert_sound(top)After a sound is played
watchdog_alert_url(top)After a URL is launched
watchdog_freeze_screen(top)If BI is detected as being frozen
watchdog_ip_change(top)IP address changes - DDNS Watchdog must be enabled
watchdog_max_alerts(top)Maximum Watchdog alerts per hour are reached
watchdog_trigger_any(top)Any Watchdog is trigger (Program, CPU, DDNS, etc.)
watchdog_trigger_cloud(top)BIT Cloud Watchdog is triggered
watchdog_update_manager_trigger(top)Update manager triggered. Handler is triggered after the update is backed up.
Basic Add-on Tips To Remember(top)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