UltraZohm components library

Before starting with the description and instructions on how to use the database system in Altium, a brief overview of the different tools is given.

../../../_images/200_Overview_DB_system.png

Fig. 254 Overview of the databased system for Altium.

The library system splits up in three different locations:

  1. The altium_libraries repository. All schematic symbols and PCB footprints of the individual components as well as the DbLib file that is required to connect to the database on the Ultrazohm server is located in this repository

  2. The UltraZohm server: All component parameters like Manufacturer Part Numbers etc. are managed by a MariaDB database on the server. In order to edit database records a separate database client (e.g. DBeaver) is recommended.

  3. User’s PC: The PC of the PCB developer gets access to the locations 1 and 2 and the developer is able to place the components. In case he has write access he can also edit and add components.

In the following, the individual tools and necessary installation steps are discussed.

Note

All usernames and passwords can be obtained from the UltraZohm core developer team. Please get in touch via the Slack channel!

In order to use the database driven library for Altium, a few settings need to be made initially. In the following chapters are a guideline on how to install and set the parameter is given. The following tools are required:

  • Bitbucket

  • ODBC Data Sources (64-Bit)

  • Altium

  • DBeaver

Videos of the setup

Note

The login information and user name in the videos do not match the real login data. Please get in touch via Slack to obtain the login information.

How to install Altium:

How to install the Altium library:

How to install DBeaver:

Bitbucket access setup

  1. To work with the databased library system in Altium, it is necessary to get access to the Bitbucket system of the UltraZohm, especially to the altium_libraries repository

../../../_images/1_BitBucket.png

Fig. 255 Bitbucket - altium_libraries.

  1. Clone the repository on your local computer

  2. If you intent to add new components, create a new feature branch. Follow the naming convention feature/<meaningful_name>. If the git shell interface is used the command is git checkout -b feature/<branch_name>

  3. If a new component was added, commit and push the new component to Bitbucket

  4. When component editing is finished open a pull request on Bitbucket. The components will be reviewed and merged into the master branch.

Server access setup

Altium needs to get access to the database system on the UltraZohm server. The interface to the database is an ODBC database driver.

  1. If not done yet download and install the MariaDB ODBC 3.1 Driver

  1. Open the ODBC-Datasource App (64-Bit)

../../../_images/20_ODBC_sources_1.png

Fig. 257 OBDC - open App.

  1. Add a new User-DSN

../../../_images/21_ODBC_sources_2.png

Fig. 258 OBDC - add user-DSN.

  1. Select the MariaDB ODBC 3.1 Driver

../../../_images/22_ODBC_sources_3.png

Fig. 259 OBDC - select MariaDB.

  1. Create a new data source to MariaDB. Use the predefined user “altium_user” and contact your supervisor for the access data.

../../../_images/23_ODBC_sources_4.png

Fig. 260 OBDC - create a new data source.

  1. Connect it to the ultrazohm server

../../../_images/24_ODBC_sources_5.png

Fig. 261 OBDC - connection to ultrazohm server.

Note

The ODBC connection is read only because no changes on the database will be made from Altium directly. A separate database client e.g. DBeaver is used to edit the database (see Integration in Altium).

  1. Do nothing and press Next >

../../../_images/25_ODBC_sources_6.png

Fig. 262 OBDC - skip.

  1. Do nothing and press Next >

../../../_images/26_ODBC_sources_7.png

Fig. 263 OBDC - skip.

  1. Force to use TLS and go back for three times < Previous

../../../_images/27_ODBC_sources_8.png

Fig. 264 OBDC - use TLS.

  1. Select the database “altium_library” and Test DSN

../../../_images/28_ODBC_sources_9.png

Fig. 265 OBDC - select “altium_library”.

  1. Finish the settings by pressing three times OK

../../../_images/29_ODBC_sources_10.png

Fig. 266 OBDC - finish settings.

Integration in Altium

  1. Open a schematic document in Altium

  2. Choose the point place –> part; a menu on the left or right side will open with the already installed library preferences called “components”

../../../_images/30_Elsys_mariadb_lib.png

Fig. 267 Altium - component libraries.

  1. Click on the three horizontal lines and select the point File-based library Preferences

  2. Select the register Installed. While not necessary, it is strongly recommended to remove all not required libraries at this point (e.g. the standard “Miscellaneous Devices” library from Altium)

../../../_images/31_File_based_lib.png

Fig. 268 Altium - installed libraries.

  1. Select Install… and navigate to the path where the Bitbucket repository is cloned on the computer. Select the file “user.DbLib”

  2. Close this window

  3. After installing the DBLib - File, you can choose between the different integrated component tables

../../../_images/32_Elsys_mariadb_lib_example.png

Fig. 269 Altium - different component tables.

  1. Now you can use all already existing components from the databased library

Setup of the database client

If new components are required the developer will need write access to the Bitbucket repository and to the database on the UltraZohm server. A dedicated user called altium_developer is available on the database system for this purpose. He has write access to the whole library database. As a graphical database client DBeaver is recommended.

  1. Download the Dbeaver software to work with the MariaDB on the UltraZohm server

  2. Open DBeaver

  3. Select MariaDB

../../../_images/35_DBeaver_1.png

Fig. 270 DBeaver - select mariaDB.

  1. Connect it to the ultrazohm server

../../../_images/36_DBeaver_2.png

Fig. 271 DBeaver - general settings.

  1. Download the MariaDB driver, which is recommended

../../../_images/37_DBeaver_3.png

Fig. 272 DBeaver - driver settings - 1.

  1. These settings must be selected automatically after the download of MariaDB.

../../../_images/38_DBeaver_4.png

Fig. 273 DBeaver - driver settings - 2.

  1. Select use SSL and uncheck Verify server certificate in the SSL tab

../../../_images/39_DBeaver_5.png

Fig. 274 DBeaver - SSL settings.

  1. Click Finish. At this time, you are able to connect to the database

  2. If the connection failed, control the settings and reconnect via right click on the altium_library –> Invalidate/ Reconnect

  3. If the connection was successful, the following table structure must be visible

../../../_images/40_DBeaver_altium_lib.png

Fig. 275 DBeaver - table structure.

This step completes the initial setup.

Addition of a new component

In the following chapter the procedure to add a new component is illustrated by adding an SMD capacitor. The following chapter only explains the addition of the component to the repository and the database. Furthermore, the developer who adds the component has to make sure that the footprint follows the mapping of the mechanical layers. See Mapping of the mechanical layers for further information. If the component does not follow this mapping the pull request will not be accepted.

Note

The goal of this database system is that schematic and footprints of generic components only exist once. This means that schematics and footprints symbols of generic components only have to be in the Bitbucket repository once, even if there are multiple physical components available (e.g. different manufacturers and values). Only if the component has a different geometry or pinout, a new schematic and/or footprint must be added. The number of pins on the symbol must match the number of pins on the footprints. The mapping of the pins is done with the pin numbering (pin 1 of the symbol is mapped to pin 1 of the footprint and so on). In case of doubt the symbol and the footprint supplied by the manufacturer must be used instead of using an existing footprint.

  1. Check if the schematic symbol already exists as a symbol in the Bitbucket system. The schematic symbols are located under alitum_libraries\symbols If the schematic does not exist, copy the schematic symbol in the suitable directory under alitum_libraries\symbols. It is vital that the .SchLib file only contains one symbol. See Symbols and Footprints on how to extract the symbol from different sources.

../../../_images/41_Explorer_SCH.png

Fig. 276 Explorer - symbols.

  1. Follow the naming convention for the .SchLib file SCH - <directory> - <description>.SCHLIB

Note

The extension of the file is written in capital letters.

  1. Check if the footprint symbol already exists in the Bitbucket system. If the component does not exist copy the footprint in the suitable folder of the footprints \alitum_libraries\footprints. It is vital that the .PcbLib file only contains one symbol. See Symbols and Footprints on how to extract the symbol from different sources.

../../../_images/42_Explorer_PCB.png

Fig. 277 Explorer - footprints.

  1. Follow the naming convention for the .PcbLib file PCB - <directory> - <description>.PCBLIB

Note

The extension of the file is written in capital letters.

  1. Switch to the DBeaver tool

  2. Choose a suitable table where the component should be added. If no table is suitable go on with the instruction given in section Addition of a new table.

Warning

This option must only be chosen after talking to your supervisor and must be announced in a pull request. When adding a new table, the .DbLib file, which implements the connection from Altium to the database, must be changed and all users need to update the file in order to get access to the new table. In case of doubt put the component in an existing table. The current amount of tables should be sufficient to fulfill the requirements.

../../../_images/43_DBeaver_table.png

Fig. 278 DBeaver - choose a suitable table.

  1. A new register on the right side with the table will appear

../../../_images/44_DBeaver_Properteries.png

Fig. 279 DBeaver - Editor will open on the right side.

  1. Switch to the “Data” register. An overview of all already added components will be shown there.

../../../_images/45_DBeaver_Data.png

Fig. 280 DBeaver - change to tab “data”. In this case, no component is still existing in the table.

  1. Press the add button and a new row highlighted in green appears.

  2. Double click on a cell to enter content.

  3. To switch between the view of all components and the comfortable editing mode for one component –> press tab.

12. If all necessary cells are filled with information, save the components with the save button (under the current table on the left side or by pressing Ctrl + S). Some cells are constraint to be NOT NULL. These cells must be filled before saving is allowed. If those cells are not filled the following message will occur.

../../../_images/46_DBeaver_Data_Error.png

Fig. 281 DBeaver - error message.

Press OK and fill out the missing cell (in this example, “ComponentLink1Description”). The table cells, which are here described in detail is from “Capacitors - SMD” table as an example.

Table 115 Capacitors - SMD

Cell name

Value

Explanation

Must be filled

PartID

Automatically added

Created On

Automatically added

Comment

Value

ComponentLink1Description

datasheet

Homepage/ Datasheet

x

ComponentLink1URL

https://www.mouser.de/datasheet/2/281/c03e-516224.pdf

URL Link to homepage or datasheet

x

ComponentLink2Description

See “ComponentLink1Description”

ComponentLink2URL

See “ComponentLink1URL”

ComponentLink3Description

See “ComponentLink1Description”

ComponentLink3URL

See “ComponentLink1URL”

ComponentLink4Description

See “ComponentLink1Description”

ComponentLink4URL

See “ComponentLink1URL”

ComponentLink5Description

See “ComponentLink1Description”

ComponentLink5URL

See “ComponentLink1URL”

ComponentLink6Description

See “ComponentLink1Description”

ComponentLink6URL

See “ComponentLink1URL”

Component Type

Type of the component

x

Description

A descritption make the usage of the component easier to the designer

x

Device Package

603

0603/ 0805…

Footprint Path

footprints/Capacitor - Chip/PCB - CAPACITOR - CHIP - CAPC_0603.PCBLIB

Path were the footprint is saved

x

Footprint Path 2

See “Footprint Path”

Footprint Path 3

See “Footprint Path”

Footprint Ref

C_0603

Name in the Altium Library

x

Footprint Ref 2

See “Footprint Ref”

Footprint Ref 3

See “Footprint Ref”

Last Updated

Automatically added

Last Updated

Manufacturer

muRata

Manufacturer

x

Manufacturer Part Number

GCJ188R71H103KA01D

Manufacturer Part Number

x

Minimum Order

Minimum Order

Mounting Type

SMD

SMD/ THT

Operating Temperature

-55 - 125°C

Operating Temperature

Series

GCJ

Series

Supplier 1

Mouser

Supplier

x

Supplier Part Number 1

81-GCJ188R71H103KA1D

Supplier part number

x

Supplier 2

Supplier

Supplier Part Number 2

Supplier part number

Supplier 3

Supplier

Supplier Part Number 3

Supplier part number

Supplier 4

Supplier

Supplier Part Number 4

Supplier part number

Supplier 5

Supplier

Supplier Part Number 5

Supplier part number

Supplier 6

Supplier

Supplier Part Number 6

Supplier part number

Library Path

symbols/Passives/SCH - PASSIVES - CAPACITOR.SCHLIB

Path were the schematic symbol is saved

x

Library Ref

Capacitor

Name in Altium schematic library

x

Type

Standard

Altium component types see the Altium manual

x

Tolerance

10%

Tolerance

Voltage Rating

50 VDC

Voltage Rating

Value

0.01 µF

Value

x

Created from

MGremer

Designer

Verified by

Verfikator

Live Cycle Status

1

1: new design

x

2: verified

3: in use

LCSC Part Number

LCSC Part Number component description for ordering and assembly at JLC PCB

Stock number

Labor SMD Container

Stock number of the ELSYS component stock

  1. If the component is saved in DBeaver, refresh the view in Altium via F5 –> choose place –> part and select the library where the component has been added –> the new component is shown with all the inserted database information

../../../_images/47_Altium_Parameter1.png

Fig. 282 Altium - component information - 1.

../../../_images/48_Altium_Parameter2.png

Fig. 283 Altium - component information - 2.

../../../_images/49_Altium_Parameter3.png

Fig. 284 Altium - component information - 3.

  1. The component can now be used in the schematic by drag and drop or by selecting via right-click place ...

  2. If the added component is not visible in the library, refresh via F5 again

  3. If a new table was added in the database, open the user.DbLib File (also included in the Bitbucket folder)

../../../_images/50_Altium_database_include.png

Fig. 285 Altium - user.DbLib File.

  1. At the end of the adding process of a component commit and to push the new components for other users in Bitbucket and open a pull request to the master branch.

Addition of a new table

Warning

This option must only be chosen after talking to your supervisor and must be announced in a pull request. When adding a new table, the .DbLib file, which implements the connection from Altium to the database, must be changed and all users need to update the file in order to get access to the new table. In case of doubt put the component in an existing table. The current amount of tables should be sufficient to fulfill the requirements.

If the component you intend to add does not fit in the existing tables a new table must be created. In the following this procedure is described:

  1. Open the SQL Editor in DBeaver

../../../_images/190_Open_SQL_Editor.png

Fig. 286 DBeaver - Open the SQL Editor in DBeaver.

  1. On the Bitbucket system the sql File “create_tables.sql” is available

../../../_images/191_Create_File.png

Fig. 287 Bitbucket folder - Open the sql File “create_tables.sql”.

In this file you can find the syntax for creating a new table.

  1. Create the various relevant table columns by copying the following rows:

../../../_images/192_Table_Parameter_1.png

Fig. 288 DBeaver - Parameter - Part 1.

Edit only the name of the table (in this example: “Logic - Buffer and Driver”) to the new one. Copy all rows without editing

  1. Add between the field “Type” and “Value” all categories specific values like “power loss”, “tolerance”, “voltage rating” etc.

../../../_images/193_Table_Parameter_2.png

Fig. 289 DBeaver - Parameter -Part 2.

  1. Excute the sql statement

../../../_images/194_Execute_statement.png

Fig. 290 DBeaver - Execute the sql statement.

  1. Now it is possible to add new components to this table by following the instructions in section Addition of a new component.

7. If components were added to the table, it is necessary to change one setting in Altium for this table once. Therefore, open the “user.DbLib” file in Altium.

  1. Select the necessary table.

  2. Change under Field Settings the point Database field from “choose field” to Manufacturer Part Number

../../../_images/195_Database_field.png

Fig. 291 Altium - Change database field.

  1. Save the new settings in the “user.DbLib” file and commit it to the Bitbucket system for all the other users.