Customizing SmartCAM

The following outlines the best practices to use when customizing SmartCAM. This topic gives some general information and specific practices to use when working with SmartCAM customizations. This includes working with toolbars, report format files, tool graphics, and macro automations.

For additional information on the topic see:

 

Overview

The most important rule is "don't reuse SmartCAM shipped files."

The files shipped with SmartCAM are not guaranteed to remain unmodified by subsequent SmartCAM installations. SmartCAM often updates these files with new capabilities, removes older obsolete functionality, and occasional reorganizations to reflect a better work flow. If you want to make changes to the shipping content, always make a new copy of the files and work with the copies, rather than the original shipped files.

The following includes suggestions on how best to work with SmartCAM's customization abilities. The goal being to minimize the effort required to re-enable your customizations after SmartCAM updates and new SmartCAM version installations.

Contents Information

 

KBM Database Management

SmartCAM uses the SQLite server-less SQL database engine for managing the Process Parameter and KBM Library information. Unlike traditional SQL engines, SQLite does not use a client/server model; instead it directly accesses the database file. This means that file access and group permissions are used to control database read and write access; rather than unique SQL server log-in accounts and configuration.

The following provides some suggestions for managing the database file, based on common usage scenarios.

Single User

For a single user, the database file does not need to be shared. As such, very little management is required.

Database File Location

The database file should be kept in the default installed location. This would normally be: \ProgramData\SmartCAM\Common\Database\.

Permission

In a single user environment, the single user would need both read and write access. The user should have full read/write/modify permissions on the KBM Library database (*.db) file and the folder it resides in.

Multi-User

If you want multiple people to use the same database information, there are a couple of different ways this can be done. It is important to understand that having multiple people work with the same database contents has issues that the single user (each user has unique database file) method does not need to handle.

Important: the SQLite SQL database engine is designed for a multiple read clients, but not multiple concurrent writing clients. In a traditional (but more complex) client/server database environment, the database server acts as a manager staging and handling all the read and write requests to the database file. Since SQLite does not have a server, this layer of management does not exist.

For this reason, SmartCAMcnc recommends that you have a single person/machine/account that handles all the database updates - all the writing to the database. This way there is limited chance of concurrent write events, and lessens the chances of data being lost due to multiple "file lock conflict" nature of a server-less database engine.

Multiple Database Files

The easiest method for handling multiple users using the same database information is to have multiple copies of the database. One copy for each user; with only one system doing all the writing.

You have a single seat or person who handles all updates to the database. Anytime the information in the database needs to be modified, removed, or new information added - this is handled via a single seat to the "master" copy of the database.

After the Master database is updated, it is made available to all other SmartCAM seats. The users copy this updated master down and replace their current, local copy of the database file.

This method makes sure all users have the same information.

Since all the SmartCAM users are referring to a locally installed copy of the database, this version also has the best performance.

Master DB File on the Network

Another method is to place a single, shared database file on a shared drive. All SmartCAM users mount this shared drive and refer to the same file.

When changes are needed, the shared DB is updated. It is important, in this scenario, that the updates be scheduled while no one else is using the database. This prevents users from pulling down incorrect information or running into locked file issues as the database is being changed - meaning, while the database file is being written to, others cannot read from it.

To prevent unauthorized updates, especially when using a single shared database file, it is important to manage the Windows user accounts properly. The account that will be used to update the file, needs full read/write/modify permissions on the file. All other accounts, which will be used only to read from the file, should not have write and modify permissions on the file.

Performance

If you opt to use the method where multiple users share a single database file, you should be aware of some performance related issues.

Having a local copy of the database has the best performance; as there is no network overhead involved.

If you have a choice, use the Windows Share/Mount functionality for hosting the shared database file. Internal testing has found that sharing the database file from a Windows desktop computer or Windows Server is noticeably quicker than using a Linux/Samba-based shared drive. This applies to NAS drives as well - NAS drives are Linux based and use Samba; their performance is not as good as hosting the database on a Windows PC or Windows server.

 

Folder Location

SmartCAM installs configuration files in a versioned folder, off of the Windows \ProgramData folder. For example:

C:\ProgramData\SmartCAM\SmartCAMv2025\folders

Where the SmartCAMv2025 part of the example path changes with each major release of SmartCAM. This means if you place your customizations in the versioned section of the SmartCAM folder tree, when a new major release of SmartCAM is installed, you will need to move your customizations to the new folder tree. Or, keep them in the original versioned folder tree and need to remember not to remove the older tree - even after that version of SmartCAM is uninstalled.

The suggested method is to create a customization folder in the SmartCAM ProgramData tree, but outside of the versioned section. Example:

C:\ProgramData\SmartCAM\Customization

Starting with SmartCAM v2015, the SmartCAM installations have created a new Common folder for storing unversioned files. Unversioned files are files that are commonly shared between releases and which are not often updated. Installing the files in this unversioned Common folder, simplifies later installations of new product, as the files do not need to be copied from versioned folder to versioned folders. Note, SmartCAMcnc does not recommend reusing the SmartCAM installed files - even the files in the Common folder. As when changes are made to the files, the SmartCAM installation will overwrite them.

The default location for this folder is: C:\ProgramData\SmartCAM\Common

You can use the Common folder for your personal customized files. Or create a folder for your own purposes.

It is also recommended that you create a series of subfolders, under your Customization folder, to group related files together. This will make it easier to find items later. The following shows an example of this folder tree.

[Customization Folder Tree]

The folder names and contents, above, are just suggestions. Use the structure and naming convention that makes most sense to you. However, do place the root of the folder tree outside of the versioned SmartCAM folders.

It is suggested that you create the folder in the ProgramData tree. Not in the root of the drive. Meaning, the path "\ProgramData\SmartCAM\Customization" is better than "C:\Customizations." This is not SmartCAM related; this is a Windows-related issue. The way current Windows permissions-based security works, you will have less problems working with files in the ProgramData folder than in the drive root.

Any path examples used in the remainder of this topic, will reference the above example folder tree.

 

Toolbars

Issues related to working with customized application toolbars.

Toolbar Set Files

The Toolbar Set files (.BFG19) contain references to each imported toolbar file (the file that contains the list of buttons or icons to display), whether or not the toolbar is displayed, the orientation and location of the toolbar, the size of the toolbar's buttons, and whether or not button text is displayed and where it is displayed. In effect, it contains the toolbar layout.

If you are going to make changes to the default shipping layouts, it is highly recommended that you establish your own Set file to use. The Toolbar Set files could be replaced or changed with any update of SmartCAM. Instead, we recommend using the shipping files as templates and creating your own Set file and make changes to this file.

Selecting a Set File

You can select which Toolbar Set file to use two ways. You can use Utility - Toolbar Sets - Choose or you can right-click on the Main Menu and select Choose Toolbar Set... from the pop-up menu. A File Open window is displayed. You browse to where your Set files are located and select the file to use. The Toolbar Set files have a .BFG19 file extension.

SmartCAM will update and show the new toolbar configuration.

Creating a Toolbar Set File

There are two methods for creating a new Toolbar Set file. You can make a copy of the current configuration or you can create a completely empty set.

Regardless of which method you use, it is recommended that you do not save the file in the default Toolbar Set location. By default, the shipping toolbars are installed in a folder tree that contains SmartCAM's version number. For example: ...\SmartCAMv####\SHARED\ICON. Having your custom toolbars and toolbar configuration files in this versioned folder makes it harder to find and update later.

Instead, SmartCAM creates a folder area that is safe to use between versions. The folder is: \ProgramData\SmartCAM\COMMON\. Nothing in this tree is updated by subsequent SmartCAM updates and nothing in this tree is really affected by uninstalling older versions of SmartCAM.

It is recommended that you create a Toolbar folder, under this Common folder and use it for your custom Set and Button files. This way, if something happens and you need to find and reload this toolbar layout, you know where it resides. And it is safe from future updates.

Creating a Copy of Toolbar Set

To make a copy of your current toolbar layout, so that you can make changes to it, you can used the main menu command Utility - Toolbar Sets - Copy or right-click on the main menu bar and select Copy Toolbar Set... from the pop-up menu. A File Save As window will open; browse to where you want to save the Toolbar Set file and provide the filename. This newly saved configuration will immediately become the current Set.

Creating a New Toolbar Set

While the Toolbar Set Copy options create duplicates of your current Toolbar Set, if you want to start completely fresh you can create a completely empty configuration by using Utility - Toolbar Sets - New or right-clicking on the main menu and selecting New Toolbar Set... from the pop-up menu. This opens a File Save As window and you need to browse to your destination folder and provide a name for the new file. This new, empty Set file will become the currently active configuration. You can now start importing and configuring your toolbars.

Modifying SmartCAM shipped toolbars

It is not recommended to make changes to the shipped SmartCAM toolbars. These bars could be replaced or changed with any update of SmartCAM. Instead, we recommend you use the shipped toolbar as a template for making your own; which is what these instructions cover.

To use a shipped SmartCAM toolbar as a template for your toolbar, do the following.

  1. Right-click on the toolbar you want to change, and select Toolbar - Copy from the pop-up menu. A Save As dialog will be displayed, showing a default name for the new toolbar. The default name will be the filename of the original toolbar with "_Copy" added.
  2. In the Save As dialog, browse to your Customization folder, then to the Toolbars subfolder. This is where you should save your custom toolbar. Unless you want to use the default filename, enter a filename for the custom toolbar. Click on Save to create the new toolbar.

    So, the path used to save the toolbar could look like: \ProgramData\SmartCAM\Customization\Toolbars\MyMainTool.19.

    The copy of the toolbar will immediately be added to your application. It will appear next to the original that you copied. Outwardly, it will look exactly like the toolbar you started with.

  3. You do not need the original, SmartCAM shipped, toolbar any longer. So, right-click on the original toolbar and select Toolbar - Hide. The original toolbar will disappear and your copy will take its place.
  4. If you right-click on the Main Menu bar, you will see a list of all the toolbars that SmartCAM knows about. Visible toolbars have a check mark next to the filename.

    The copy of the toolbar that you made shows up in this list. The name of the toolbar is the name of the original toolbar with "_Copy" added.

    To change the named displayed in the Main Menu pop-up menu, right-click on the toolbar and select Toolbar - Configure; which opens the Configure Toolbar dialog window.

    Please note that the toolbar's name is descriptive text, it is not the filename for the file.

    Make sure the Bar field is showing the correct toolbar. Then in the Name input field, enter your name for the toolbar. This is the name you will see on the Main Menu pop-up menu.

  5. Apply your change, if you are working on multiple toolbars. Or use Accept to save the Name change and close the Configure Toolbar dialog window.

Your toolbar is now configured and ready for you to edit as needed.

Creating a new toolbar

To create a new, blank toolbar use the following steps.

  1. Select Utility - Toolbars - New to open a Save As dialog.
  2. Browse to the location where your customer toolbars are located; for example: \ProgramData\SmartCAM\Customization\Toolbars.
  3. Replace the default File name, of Untitled.bpg, with a more descriptive name. Then click on Save to create the new blank toolbar.
  4. A new, blank toolbar will be displayed in your application. If you right-click on the Main Menu toolbar, you will see a list of the toolbars that SmartCAM knows about. Your new toolbar will be listed. The name shown will be the filename you gave it.
  5. Right-click on the new toolbar, and select Toolbar - Configure. This opens the Configure Toolbar dialog window. From here, give the toolbar a more descriptive name.

    Make sure the Bar entry is showing the correct toolbar. Then in the Name field, enter a short descriptive name for the toolbar. This is the name that will be shown in the Main Menu pop-up window.

    Please note that the toolbar's name is descriptive text, it is not the filename for the file.

    Click on Accept to store the new Name and close the dialog window.

Your new toolbar is now ready for you to populate it with buttons and position it where you want it located.

Adding, Removing and Changing toolbar buttons

You can add or remove toolbar buttons from within SmartCAM.

Adding a new button

To add a button to a toolbar:

To create a macro button (a button that triggers a macro), complete the same steps; except, instead of moving the button from the Predefined list, use the Add Macro button and define the new toolbar icon.



Removing a button

To remove a button from a toolbar:

After SmartCAM Updates

If your custom toolbars are missing, after doing a SmartCAM update or installing a new major version of SmartCAM, you can easily add them back.

Use Utility - Toolbars - Add to display an Open dialog. Browse to the location where you are keeping your custom toolbars; for example: \ProgramData\SmartCAM\Customization\Toolbars and then click on the .BGP19 toolbar file to open it.

Your custom toolbar will be displayed. You can now position it as needed.

 

JOS Reports

The File - JOS Report dialog window allows you to select both the path and filename of the source report format files and the destination folder for the final report. By default, these both use the unversioned SmartCAM ProgramData folder; reading and writing from the Reports subfolder.

The default location for these files and the Output folder is: C:\ProgramData\SmartCAM\Common\Reports

If you use the default report generators and either you don't need to keep the final reports or you have a different method of archiving them, then nothing else need be done. Do keep in mind, that the default SmartCAM report format files may be changed during any SmartCAM update or upgrade.

If you want to keep the generated reports in the location where they were initially created, you should change the Output path to a location outside of the versioned SmartCAM folder tree. Using the above example folder tree, consider:

\ProgramData\SmartCAM\Customization\Reports\Output\

If you are modifying a SmartCAM supplied report format or creating a new report format, you should rename the files - so that future SmartCAM installations do not overwrite the files. Or, copy the existing report files to a new custom folder that contains only files maintained by your company. Such as:

\ProgramData\SmartCAM\Customization\Reports

When modifying a SmartCAM report file, copy all the related format and support files to your new Reports folder. Review the main report format file and find all the files that it includes, then copy those files to the new destination. Additionally, some formats, such as the HTML report make use of supporting files, you will need to copy those files as well. For example, the HTML report makes use of CSS and PNG files that are in the Output folder - these files would also need to be copied to the new Reports\Output folder.

SmartCAM installations may change SmartCAM supplied report files, but it will not modify any custom reports that you create. The reason for creating the reports outside of the versioned SmartCAM folder tree is so that when you install a new major version of SmartCAM and the versioned folder tree changes, you can completely uninstall the older version of the application. Without moving the customized report files, you would need to keep the old versioned tree in place so that you have access to the report format files.

Your application's help file, contains a number of topics related to the JOS Reports functionality. Learning SmartCAM includes considerable information on this topic. Refer to the Using SmartCAM - Reports overview and JOS Report Format Commands child document. See the Data Tags and Section Numbers topics, under Using SmartCAM in the table of contents. See the Customizing Format Files topic, under Using SmartCAM, and it's subtopics. For a step-wise tutorial on creating a new report format file, see the tutorial topic Creating a Custom JOS Report Format File.

After a new major number SmartCAM update, the paths on the JOS Reports dialog may be set to point to the new versioned Reports folder. To use your custom reports, simply reselect the Format file and Output folder on the dialog.

 

Automations

There are a number of aspects related to adding customized automation to SmartCAM. But at the lowest level, the automations are based on SmartCAM macros (.MCL) alone or in combination with custom control panels or dialogs (.PCB). Some of the shipped SmartCAM functionality is based on macros and custom panels.

SmartCAM's automations are kept in the release's SHARED and SHARED\SYSMCL folders. These files are maintained by SmartCAM and could be changed in any SmartCAM update. You should not modify these files.

Store your custom automations in a folder outside of the versioned SmartCAM tree. Using the above example folder structure, the path would be:

\ProgramData\SmartCAM\Customization\Automations

Use this folder directly or a more organized tree within the folder for storing your custom macros, and macro/panel/dialog combinations. If you create help files for your custom panels, the help files should be in the same folder as the PCB files.

When running macros directly, browse to the folder where the .MCL is maintained and run it from there.

If you created a custom User menu, make sure the paths to the PCBs in the menu are pointing to your custom folder. The PCB files contain the path to the macros called by the panel. You can either use fully qualified paths for the macro paths (paths that include every folder in the tree leading up to the final filename) or a relative path based on the location of the PCB file.

If you are moving your custom macros from an existing folder to a new customization folder, check each macro and make sure any embedded paths are correct in regards to the new macro location.

For more information on automating SmartCAM or re-organizing your current automations, please review the following help sources.

 

Custom Tool Graphics

SmartCAM installed a number of custom tool graphic (CTG) files. The files are stored by machining type and unit of measure, in the versioned SmartCAM folder tree. For example, the metric CTG files for Production Milling are located at:

\ProgramData\SmartCAM\SmartCAMv#\MILL\MCTG_M

While the inch sample CTG files are located at:

\ProgramData\SmartCAM\SmartCAMv#\MILL\MCTG

The shipped sample CTG files may be overwritten by subsequent SmartCAM update installations.

SmartCAM supports a single path, per application, for the location of CTG files. This means all the CTG files that you use should be stored in a single folder. If you use the SmartCAM sample CTG files exclusively, and without modifying them, you can use the application's default CTG path, which points to the shipped sample files.

However, if you create new custom CTG files or modify the shipping samples then you should store the files in your Customizations folder. This way, files with the same name as shipping samples will not be overwritten by subsequent updates. Additionally, when you install major number SmartCAM updates, you will not need to keep your older application's folder tree in place - as that is where your custom CTGs reside. If you store your custom files outside of the SmartCAM versioned folder tree, you can complete remove older versions of the application.

It is recommended that you store all your custom CTG files, for all your SmartCAM applications, in a single location. Using the example path, from above, that would be:

\ProgramData\SmartCAM\Customization\Custom_Tool_Graphics

To point to this new folder location, for each SmartCAM application, modify one Step and change the Custom Tool Graphics path to your new folder location, or create a new Step in a new or existing process model and point that tool's CTG folder to your new location. Once the path is changed for any new or existing Step, the path is changed for all process models used the given application.

You can further organize the CTG files within the common folder as needed; perhaps storing them by application or by machine type or by units. The important item to remember is that each SmartCAM application only supports a single path for all CTG files. If you change the path for one tool, you will have changed the path for all other process models handled by that application.

See the topic, Creating Custom Tool Graphics (CTG) Files, for information creating CTG files.

 

Customer Data

The important concept here is to store your companies' Process Model and Job Operation File (JOF) data outside of the versioned SmartCAM folder tree.

SmartCAM includes a number of sample process model files, in an organized folder tree. For example, the Production Milling metric sample files are installed into:

\ProgramData\SmartCAM\SmartCAMv#\MILL\MDATA_M\

While the inch sample files are installed into:

\ProgramData\SmartCAM\SmartCAMv#\MILL\MDATA

This is not a recommended directory structure for production work. This organization is only used to more easily help new users find sample data that they can experiment and learn from.

Users often store their process model information in a structure based on part numbers, account numbers, or some other organizing factor. This does not need to change in any fashion. However, do not create your site's organized folder tree inside the SmartCAM versioned folder area. So, for example, do not store your model files in the \ProgramData\SmartCAM\SmartCAMv#\MILL\MDATA folder.

The reason for this is that when you update to a new SmartCAM major version, you don't want a requirement that you need to keep your old SmartCAM folder tree (even after uninstalling the applications), because that is where your data is. Placing your file's folder outside the versioned area, allows it to remain unchanged between releases and allows you to completely remove older versions of SmartCAM.

The SmartCAM installations are completely unaware of your companies' process model data and will not modify it. Unless, you store your data in the SmartCAM folder tree using the same filename as a shipped SmartCAM file. At that point, SmartCAM may overwrite the file - as it shares a filename and location with a shipped file.

 

Code Generation and G-Code Files

SmartCAM ships a number of sample code generation SMF and CGT files; these are meant to be starting points for your own customized code generators. SmartCAM installations may modify, add, or remove these files; as required by changes to SmartCAM's code generation capabilities.

The sample code generator (.SMF and .CGT) file pairs are installed in the unversioned Common folder. You can add your companies SMF and CGT pairs to this folder. However, do not make changes to the files that SmartCAM installs, as they may be overwritten during future installations. You can copy and rename the files and leave them in the Common folder - they will not be affected by later installations that way. Or, if you have your own company folder for storing your customized files, copy them to that folder. Keep your SMF and CGT sets together in the same folder.

Additionally, it is recommended that you do not write your NC g-code files in the versioned SmartCAM folder. Otherwise, when you migrate to a new major release of SmartCAM, you cannot completely uninstall and remove your older version's folder tree - as your active files are contained within it.

Using the above example folder tree, you could store your SMF and CGT file pair in the \ProgramData\SmartCAM\Customization\Code_Generators folder, and write your generated NC g-code files to the \ProgramData\SmartCAM\Customization\G-Code_Files folder.