Introduction

Mates Studio’s Commander environment allows users to select and utilize different page designs/layouts from a built-in collection provided by the Breadboard Mates team and its community. This allows users to quickly produce nice-looking GUI applications in seconds.

This output program features an easy-to-use-and-understand Mates Serial Command Protocol that can allow users to control the display using their favorite microcontrollers.

This also includes a simple to use interface that allows users to simulate a microcontroller controlling the display programmed with a Commander project.

To create a new or open a Commander project file, please refer to Mates Studio User Guide.

Adding and Deleting Page Layouts

By clicking the Add Page button, a collection of pre-made page designs can be browsed.

The Page Selection Window will appear as shown:

Page designs can be filtered by choosing the category tabs on the left-hand side. A special category, labeled User, contains custom designs made using Architect, Genius and Builder and is saved to Documents\Mates Studio Pages directory.

By selecting a page design from the list shown in the middle column of the window, a preview of the page will be shown on the right-hand side.

Multiple page layouts can be selected at the same time by holding CTRL key before clicking the page item.

Confirm selections by clicking on the CONFIRM button.

Alternatively, a Browse Computer option is provided to allow loading of page templates located in other PC directories.

Navigate to the location of the page (matesPage) file.

Confirm selections by clicking on the Open button.

Newly added pages will be added and shown in the left-hand side. A short documentation is also automatically generated for every page that is added. It is displayed in the right-hand side of the window.

By clicking on the page items on the left-hand side, the documentation will update to match the last clicked page item. The discussion generated contains code snippets that can be used together with Mates Serial Command libraries

Pages not required in the project can easily be deleted by using the delete button included in the page preview shown in the left-hand side of the window.

Identifying the Correct Port

To successfully upload a project, update the firmware and control a programmed display, the correct target port needs to be selected.

The easiest way to confirm if you are using the correct port is by opening Window’s Device Manager.

Before connecting the module to the computer, open Device Manager. Next, connect the module and the window will refresh.

As shown under Ports (COM & LPT), a device is now connected to COM6. If multiple devices are shown, the device recently added is the correct port.

Selecting the Target Port

After identifying the correct port, the target port for the project can be selected.

As shown above, there is no port detected. By clicking on the dropdown menu, the application will search for connected ports that the target product might be using.

Saving the Project

Selecting the Target Product Configuration

Save projects by clicking the Save icon button and selecting Save Project.

For a new project, a Save Project window will open to request for the location and filename to use when saving.

A previously saved project can also be saved to a different location by selecting the Save Project As option instead.

After selecting the product and desired orientation, continue by clicking on the CONFIRM button.

Exporting as Architect Project

Commander projects can be exported as an Architect project. This allows users to edit individual widgets from pre-made page designs.

An Export Project window will open to request for the location and filename to use when exporting the project.

Uploading the Project

After finalizing the project, it can be uploaded to the target device specified by the selected port.

Before uploading, the following needs to be confirmed:

  • The port selected is correct and the target product is connected.
  • The port selected is not being used by other applications or other Mates Studio windows. (Read section Connecting to the Module for a tip on how to easily confirm that the port is not busy)

After checking the items above, upload the project by clicking the Upload button.

Uploading unsaved projects will automatically open a Save Project window before the application proceeds with uploading the project to the target device.

The project will be compiled for graphical resources.

Afterwards, an information window containing the compilation results will be shown.

Click Proceed to continue with the upload.

The graphical resources will be uploaded, and the display will be programmed with the Commander project.

Simply wait for the process to finish successfully. Once it completes, the module will show the first Page of the Commander project.

Project Configuration and Tools

This section discusses tools and project configurations which can be used and modified.

Note: When using any of these tools and project configurations, it is important to reupload the project.

Loading (PmmC) Firmware

All BBM products are factory-programmed with the latest stable firmware from 4D Labs. Firmware updates contain improvements and bug fixes. Therefore, it is ideal to load the latest version available during development.

The Commander environment provides a simple way to load any firmware provided with Mates Studio for the target product.

If there’s currently no COM port selected, an error window will be shown prompting to set a COM port before loading the firmware.

Otherwise, the Load PmmC window will open.

As shown, a recommended latest version will be labeled. Click on the target item to select the firmware version.

To proceed with the loading the selected item, click the Upload button.

Wait until the upload finishes.

The window will automatically close a few seconds after the upload completes.

Reversing Orientation

The commander environment only allows inverting a project’s orientation.

Since this environment does not provide editing capabilities for widgets, rotating the orientation by 90 or 270 degrees is restricted.

Page Transitions

Commander environments provides different transition effects. By default, None or no transition effect is applied in a project.

Project Baudrate

By default, Commander projects use 9600 baud for Mates Serial Command Protocol.

This can be changed by clicking some alternative options as shown.

Runtime Mode

As previously discussed, the Commander environment doesn’t feature design time changes to widgets. Instead, it offers the option to change certain widget parameters during runtime using Mates Serial Commands.

By default, the Commander uses Fixed runtime mode. In this mode, widget colors cannot be modified during runtime. This mode consumes less code space and memory and is more stable than the alternative option.

Additional Options

Creating a New Project

The setup window can be opened from a Commander window by clicking the New Project button as shown:

This will open the same window as shown when opening Mates Studio. Please refer to the Mates Studio User Guide for more information.

Opening a Project

An Open Project window can be opened directly from a Commander project by clicking the Open Project button as shown:

This option will open a file selection window for you to find and select a project file to open.

Software Information

The application version can be checked by clicking the button as shown:

This will open a small window containing version and contact information.

Controlling a Programmed Module

After uploading a Commander project, the Control tab can be used to control the connected display module.

The Control tab provides the following:

  1. Page Navigation column
  2. Main Control column
  3. Command Viewer column

Connecting the Module

To communicate and control the display, the application needs to first connect to the module. After confirming the selected port, click the Connect button to establish connection.

The LED indicator will display a bright color after successfully establishing connection.

It is also IMPORTANT to ensure that the module sends the ready signal before using the controls. This can be checked from the Command Viewer column as shown:

Tip: Connecting to the display can be used to ensure that the port is not busy and is safe for reprogramming. If an error occurs when trying to connect, the port is being used by another software or another Mates Studio window.

Navigating the Pages

The display will always show the first page, Page0, initially. Other pages included in the project can easily be activated by using clicking the corresponding item in the Page Navigation column.

After activating another page, the Main Control column will show the widgets present in the active form and the Command Viewer column will show the data exchanged that happened to change the active page.

Controlling the Widgets

Different control interfaces are provided for different type of widgets. Here are some of the control interfaces for the available widgets.

  1. GET
    Retrieves the current value of the widget.
  2. ANIMATE
    Starts and ends widget animation.
  3. SET
    Sends the value specified by the input box.
  1. CLR
    Clears the printed values
  2. COLOR
    Sets the font color to use in next print.
  3. ADD
    Appends the value in the input box.
  1. ANIMATE
    Starts and ends widget animation.
  2. SET
    Sends the value specified by the input box.
  1. SET
    Sends the value specified by the input box

By using the control interfaces, the project can be simulated, and the messages exchanged by the host controller and the module will be shown in the Command Viewer column for additional reference.

Resetting the Display

The Commander environment includes an option to reset a connected display. Resetting the display involves disconnecting to the display and reconnecting.

Back to Resource Centre

Share this article on socials

Introduction

Mates Studio’s Commander environment allows users to select and utilize different page designs/layouts from a built-in collection provided by the Breadboard Mates team and its community. This allows users to quickly produce nice-looking GUI applications in seconds.

This output program features an easy-to-use-and-understand Mates Serial Command Protocol that can allow users to control the display using their favorite microcontrollers.

This also includes a simple to use interface that allows users to simulate a microcontroller controlling the display programmed with a Commander project.

To create a new or open a Commander project file, please refer to Mates Studio User Guide.

Adding and Deleting Page Layouts

By clicking the Add Page button, a collection of pre-made page designs can be browsed.

The Page Selection Window will appear as shown:

Page designs can be filtered by choosing the category tabs on the left-hand side. A special category, labeled User, contains custom designs made using Architect, Genius and Builder and is saved to Documents\Mates Studio Pages directory.

By selecting a page design from the list shown in the middle column of the window, a preview of the page will be shown on the right-hand side.

Multiple page layouts can be selected at the same time by holding CTRL key before clicking the page item.

Confirm selections by clicking on the CONFIRM button.

Alternatively, a Browse Computer option is provided to allow loading of page templates located in other PC directories.

Navigate to the location of the page (matesPage) file.

Confirm selections by clicking on the Open button.

Newly added pages will be added and shown in the left-hand side. A short documentation is also automatically generated for every page that is added. It is displayed in the right-hand side of the window.

By clicking on the page items on the left-hand side, the documentation will update to match the last clicked page item. The discussion generated contains code snippets that can be used together with Mates Serial Command libraries

Pages not required in the project can easily be deleted by using the delete button included in the page preview shown in the left-hand side of the window.

Identifying the Correct Port

To successfully upload a project, update the firmware and control a programmed display, the correct target port needs to be selected.

The easiest way to confirm if you are using the correct port is by opening Window’s Device Manager.

Before connecting the module to the computer, open Device Manager. Next, connect the module and the window will refresh.

As shown under Ports (COM & LPT), a device is now connected to COM6. If multiple devices are shown, the device recently added is the correct port.

Selecting the Target Port

After identifying the correct port, the target port for the project can be selected.

As shown above, there is no port detected. By clicking on the dropdown menu, the application will search for connected ports that the target product might be using.

Saving the Project

Selecting the Target Product Configuration

Save projects by clicking the Save icon button and selecting Save Project.

For a new project, a Save Project window will open to request for the location and filename to use when saving.

A previously saved project can also be saved to a different location by selecting the Save Project As option instead.

After selecting the product and desired orientation, continue by clicking on the CONFIRM button.

Exporting as Architect Project

Commander projects can be exported as an Architect project. This allows users to edit individual widgets from pre-made page designs.

An Export Project window will open to request for the location and filename to use when exporting the project.

Uploading the Project

After finalizing the project, it can be uploaded to the target device specified by the selected port.

Before uploading, the following needs to be confirmed:

  • The port selected is correct and the target product is connected.
  • The port selected is not being used by other applications or other Mates Studio windows. (Read section Connecting to the Module for a tip on how to easily confirm that the port is not busy)

After checking the items above, upload the project by clicking the Upload button.

Uploading unsaved projects will automatically open a Save Project window before the application proceeds with uploading the project to the target device.

The project will be compiled for graphical resources.

Afterwards, an information window containing the compilation results will be shown.

Click Proceed to continue with the upload.

The graphical resources will be uploaded, and the display will be programmed with the Commander project.

Simply wait for the process to finish successfully. Once it completes, the module will show the first Page of the Commander project.

Project Configuration and Tools

This section discusses tools and project configurations which can be used and modified.

Note: When using any of these tools and project configurations, it is important to reupload the project.

Loading (PmmC) Firmware

All BBM products are factory-programmed with the latest stable firmware from 4D Labs. Firmware updates contain improvements and bug fixes. Therefore, it is ideal to load the latest version available during development.

The Commander environment provides a simple way to load any firmware provided with Mates Studio for the target product.

If there’s currently no COM port selected, an error window will be shown prompting to set a COM port before loading the firmware.

Otherwise, the Load PmmC window will open.

As shown, a recommended latest version will be labeled. Click on the target item to select the firmware version.

To proceed with the loading the selected item, click the Upload button.

Wait until the upload finishes.

The window will automatically close a few seconds after the upload completes.

Reversing Orientation

The commander environment only allows inverting a project’s orientation.

Since this environment does not provide editing capabilities for widgets, rotating the orientation by 90 or 270 degrees is restricted.

Page Transitions

Commander environments provides different transition effects. By default, None or no transition effect is applied in a project.

Project Baudrate

By default, Commander projects use 9600 baud for Mates Serial Command Protocol.

This can be changed by clicking some alternative options as shown.

Runtime Mode

As previously discussed, the Commander environment doesn’t feature design time changes to widgets. Instead, it offers the option to change certain widget parameters during runtime using Mates Serial Commands.

By default, the Commander uses Fixed runtime mode. In this mode, widget colors cannot be modified during runtime. This mode consumes less code space and memory and is more stable than the alternative option.

Additional Options

Creating a New Project

The setup window can be opened from a Commander window by clicking the New Project button as shown:

This will open the same window as shown when opening Mates Studio. Please refer to the Mates Studio User Guide for more information.

Opening a Project

An Open Project window can be opened directly from a Commander project by clicking the Open Project button as shown:

This option will open a file selection window for you to find and select a project file to open.

Software Information

The application version can be checked by clicking the button as shown:

This will open a small window containing version and contact information.

Controlling a Programmed Module

After uploading a Commander project, the Control tab can be used to control the connected display module.

The Control tab provides the following:

  1. Page Navigation column
  2. Main Control column
  3. Command Viewer column

Connecting the Module

To communicate and control the display, the application needs to first connect to the module. After confirming the selected port, click the Connect button to establish connection.

The LED indicator will display a bright color after successfully establishing connection.

It is also IMPORTANT to ensure that the module sends the ready signal before using the controls. This can be checked from the Command Viewer column as shown:

Tip: Connecting to the display can be used to ensure that the port is not busy and is safe for reprogramming. If an error occurs when trying to connect, the port is being used by another software or another Mates Studio window.

Navigating the Pages

The display will always show the first page, Page0, initially. Other pages included in the project can easily be activated by using clicking the corresponding item in the Page Navigation column.

After activating another page, the Main Control column will show the widgets present in the active form and the Command Viewer column will show the data exchanged that happened to change the active page.

Controlling the Widgets

Different control interfaces are provided for different type of widgets. Here are some of the control interfaces for the available widgets.

  1. GET
    Retrieves the current value of the widget.
  2. ANIMATE
    Starts and ends widget animation.
  3. SET
    Sends the value specified by the input box.
  1. CLR
    Clears the printed values
  2. COLOR
    Sets the font color to use in next print.
  3. ADD
    Appends the value in the input box.
  1. ANIMATE
    Starts and ends widget animation.
  2. SET
    Sends the value specified by the input box.
  1. SET
    Sends the value specified by the input box

By using the control interfaces, the project can be simulated, and the messages exchanged by the host controller and the module will be shown in the Command Viewer column for additional reference.

Resetting the Display

The Commander environment includes an option to reset a connected display. Resetting the display involves disconnecting to the display and reconnecting.

Back to Resource Centre

Share this article on socials