Phidgets Support - User contributions [en]

Using XLights with Phidgets

2026-06-10T22:23:16Z

Mparadis: Mparadis moved page Using XLights with Phidgets to Using xLights with Phidgets

#REDIRECT [[Using xLights with Phidgets]]

Using xLights with Phidgets

2026-06-10T22:23:15Z

Mparadis: Mparadis moved page Using XLights with Phidgets to Using xLights with Phidgets

[[Category: Project]]
{{TOC limit|3}}
{{#seo:|keywords=xLights, ws2812, christmas lights}}
{{#seo:|description=Learn how to use a Phidgets addressable LED controller with xLights software.}}
==Introduction==
[[Image:xLights.png|400px|thumb|link=]]
xLights is a free and open-source comprehensive light control platform that helps create small or large light displays quickly, without the need for coding. This guide will walk you through how to add the Addressable LED Phidget as a controller in xLights.

== Demonstration ==
<center>{{#ev:youtube|G6JIiXuTe18|rel=0}}</center>

==Hardware==
This project uses the following parts:
* [{{SERVER}}/?prodid=969 PhidgetSBC4 (SBC3003_0)]
* [{{SERVER}}/?prodid=1368 Addressable LED Phidget (LED0100_0)]
* [{{SERVER}}/?tier=2&catid=28&pcid=24 USB Cable]
* [{{SERVER}}/?tier=1&catid=61&pcid=54 12V Power Supply for PhidgetSBC]
* [{{SERVER}}/?prodid=1011&pcid=77 Ethernet cable]
* 16x16 Addressable LED Array
* 5V 3.5A Power Supply for LEDs
* Windows, macOS or Linux computer

==Assembly==
[[Image:xL_setup.png|link=|700px]]

Assemble the system following these steps:
* Connect your LED array to the Addressable LED Phidget
* Connect the Addressable LED Phidget to the PhidgetSBC4 using a USB cable
* Connect the PhidgetSBC4 to your network router or switch with an ethernet cable
* Connect the 12V power supply to the PhidgetSBC
* Connect the LED power supply to the Addressable LED Phidget. Here, our LED array requires 5V.

== Server Setup ==

=== SBC Web Configuration ===
In this project, we'll be using a client (our desktop computer) and a server (the PhidgetSBC4).

To start, we need prepare the PhidgetSBC4 with the required packages and configurations. Log into the SBC's web interface by double clicking on its control panel entry:

[[Image:xL_controlpanel.png|link=|center]]

Next, follow these steps:
#Log in and navigate to '''System -> Packages'''.
#Install the '''C/C++ Development Tools/Headers'''.
#'''Refresh Available Packages''' and '''Upgrade All Packages'''

[[Image:xL_packages.png|link=|center]]

Finally, go to '''Network -> Settings''' and enable the SSH server if it isn't already enabled.

=== Installing the Server ===

Now that SSH is enabled, we can remote in with SSH software (we recommend [https://www.chiark.greenend.org.uk/~sgtatham/putty/ PuTTY]). Or, you can plug a monitor and keyboard into the SBC4 and complete the rest of this section in the terminal directly.

If you don't already have '''git''' installed, you can get it with the following commands:
<syntaxhighlight lang=bash>
apt update
apt install git
</syntaxhighlight>

If you don't already have the '''make''' command installed, you can get it with:
<syntaxhighlight lang=bash>
apt install build-essential
</syntaxhighlight>

Navigate to '''/usr/userapps/''' (you'll have to create the userapps directory if this is the first project on this SBC) and use the following command to download the server project files:
<syntaxhighlight lang=bash>
git clone https://github.com/PhidgetsInc/openpixelcontrol-ph22.git
</syntaxhighlight>

All of the files and folders for the server code will be added in a folder named '''openpixelcontrol-ph22'''.

If you're not experienced with the terminal, we recommend switching back to the SBC web interface at this point. Go to the '''Projects''' tab and you should see the project folder. Click on the folder to open it.

[[Image:xL_project1.png|link=|center]]

Scroll down and click the '''make''' button to build the project.

[[Image:xL_make.png|link=|center]]

Once it's done building you can test the server by returning to your SSH terminal and typing '''./bin/Phidget_server''' from the project folder. If it's successful, you should see this:

[[Image:xL_serverRunning.png|link=|center]]

Once the server is running, we can configure our client.

== Client Setup ==

To begin, install [https://xlights.org/ xLights] on your client computer.

=== Controller Configuration ===

Open xLights and add a new ethernet controller under the controllers tab:

[[Image:xL_controller.png|link=|center]]

* The '''Protocol''' should be set to 'OPC'.
* The '''Message Data Size''' should be equal to the number of LEDs in your display multiplied by the number of color channels. This project uses a 16x16 grid of RGB lights, so the data size is 768. For a strand of 100 RGBW lights, the data size would be 400.
* The '''IP address''' needs to be set to the SBC's IP, which you can find in the Phidget Control Panel:

[[Image:xL_IP.png|link=|center]]

=== Layout Configuration ===

The layout lets you accurately model your lights in xLights. For a simple LED strip click on "Single Line", and for a grid, use "Matrix". Then click and drag in the black space to create the model.
[[Image:xL_layout.png|link=|center]]

Once it's created, click on your model to access the options.
[[Image:xL_layoutOptions.png|link=|center]]

We won't be going in depth on all the layout options in this article, but you can find more information in xLights' official documentation. For now, the important thing is to select '''Use Start Channel''' for the controller. Next, click on start channel and click on the '...' that appears. For '''Universe number''' select the IP address of the SBC.
[[Image:xL_universe.png|link=|center]]

In order to have our 16x16 grid display properly, the Strings, Nodes/String, and Strands/String must be set to 4, 64, and 4. This is because the LEDs are laid out in a zig-zag pattern. If you're using a strip, you can just set it to 1, N, 1, where N is the number of lights in your strip.

=== Sequencer ===

Once your controller and layout are set up, you can move to the sequencer tab and do '''File -> New Sequence'''. Select 'Animation', '40fps', and 'Quick Start'.

Now you can choose one of the effects from the effects bar and drag it into the row in the timeline corresponding to the layout you created. Drag it out so it lasts longer than a few seconds. Click on the play button, and you should see the effect play out on the preview in the bottom left. You can play with the Effect Settings and Colors windows to customize the effect.
[[Image:xL_timeline.png|link=|center]]

Further details on creating sequences fall outside of the scope of this article, but you can see the official xLights documentation for more information.

Now that your sequence is set up, you can click the lightbulb icon to attempt to connect to the SBC's server.
[[Image:xL_bulb.png|link=|center]]

If it's successful, you'll see the IP address of your client appear in your SSH terminal:
[[Image:xL_sshConnect.png|link=|center]]

When you hit play, you should see your lights activate.

[[Image:animation.gif|link=|center]]

== Running the Project on Boot ==

Now that you've confirmed the server and client work using SSH or a local terminal, we can set the program to launch on boot as a daemon.

Open the SBC web interface again and navigate to your project. Scroll down to '''Startup Settings''' and enable it, selecting '''bin/Phidget_server''' as the executable and clicking the save button below.

[[Image:xL_startup.png|link=|center]]

The next time you power cycle the SBC, the server will run and you should be able to connect with your xLights client.

== Running Autonomously on the SBC ==

You may find that having a second computer running the xLights app 24/7 is a bit overkill for the size and scope of your project. If you just want the SBC to run a few patterns on a loop all by itself, but you still want to use xLights to design the pattern, you can have the SBC act as both client and server for the OPC stream.

Open an SSH connection and go back to the /userapps/ directory on your SBC. Run the following command:
<syntaxhighlight lang=bash>
git clone https://github.com/PhidgetsInc/opcdecode-ph22.git
</syntaxhighlight>

This project requires '''libzstd''' to run. Install it with the following command:
<syntaxhighlight lang=bash>
apt install libzstd-dev
</syntaxhighlight>

You should now have a second project visible in the SBC web interface:

[[Image:xL_project2.png|link=|center]]

Click on openpixelcontrol-ph22 and start the project:

[[Image:xL_startProj.png|link=|center]]

Then go back and do the same for opcdecode-ph22. You should see your lights turn on and display the default pattern.

You can now configure both projects to run on boot as we did in the previous section, which will cause the pattern to display autonomously on boot, even if the SBC isn't connected to any network. You can design and save your own sequence in xLights and copy the .fseq file to the SBC to customize the pattern.

Using xLights with Phidgets

2026-06-10T22:11:43Z

Mparadis: Created page with "Category: Project {{TOC limit|3}} {{#seo:|keywords=xLights, ws2812, christmas lights}} {{#seo:|description=Learn how to use a Phidgets addressable LED controller with xLights software.}} ==Introduction== link= xLights is a free and open-source comprehensive light control platform that helps create small or large light displays quickly, without the need for coding. This guide will walk you through how to add the Addressable LED Phidge..."

File:XL startProj.png

2026-06-10T22:11:03Z

Mparadis:

File:XL project2.png

2026-06-10T22:10:48Z

Mparadis:

File:XL startup.png

2026-06-10T22:10:36Z

Mparadis:

File:Animation.gif

2026-06-10T22:10:25Z

Mparadis:

File:XL sshConnect.png

2026-06-10T22:10:17Z

Mparadis:

File:XL bulb.png

2026-06-10T22:10:06Z

Mparadis:

File:XL timeline.png

2026-06-10T22:09:56Z

Mparadis:

File:XL universe.png

2026-06-10T22:09:46Z

Mparadis:

File:XL layoutOptions.png

2026-06-10T22:09:38Z

Mparadis:

File:XL layout.png

2026-06-10T22:09:25Z

Mparadis:

File:XL IP.png

2026-06-10T22:09:17Z

Mparadis:

File:XL controller.png

2026-06-10T22:08:28Z

Mparadis:

File:XL serverRunning.png

2026-06-10T22:08:16Z

Mparadis:

File:XL make.png

2026-06-10T22:08:07Z

Mparadis:

File:XL project1.png

2026-06-10T22:07:52Z

Mparadis:

File:XL packages.png

2026-06-10T22:07:41Z

Mparadis:

File:XL controlpanel.png

2026-06-10T22:07:20Z

Mparadis:

File:XL setup.png

2026-06-10T22:07:11Z

Mparadis:

File:XLights.png

2026-06-10T22:06:46Z

Mparadis:

Language - C

2026-05-27T19:58:04Z

Mparadis: /* GCC */

{{#seo:|description=Learn how to use Phidget USB devices with C and C++.}}
[[Category:Language]]

== Get Started ==
With the Phidget22 library, it's easy to create C or C++ applications that work with Phidget devices.

== C Libraries ==
If you've installed the Phidget drivers for [[OS - Windows|Windows]], [[OS - macOS|MacOS]], or [[OS - Linux|Linux]], then you already have the files you need for your C project.

==== Windows Considerations ====
When adding directories for your project dependencies, add
<syntaxhighlight>
C:/Program Files/Phidgets/Phidget22
</syntaxhighlight>
And for the linker, you can add
<syntaxhighlight>
C:/Program Files/Phidgets/Phidget22/phidget22.lib}} #(for 64-bit systems)
C:/Program Files/Phidgets/Phidget22/x86/phidget22.lib}} #(for 32-bit systems)
</syntaxhighlight>

====macOS Considerations====
Legacy Phidgets running a HID USB stack require a driver extension (macOS 10.15 and newer) or a kernel extension (macOS 10.14 and earlier). During development, we recommend downloading the appropriate [https://www.phidgets.com/docs/OS_-_macOS#Quick_Downloads package] which will install the extension. When deploying applications, review the README in the [https://cdn.phidgets.com/downloads/phidget22/libraries/macos/Phidget22_macosdevel.zip macOS Development Files] for information about bundling the extension with your application.

=====Determining USB Stack=====
To determine which USB stack your device is running, navigate to the product page and then to the specification tab, and look for the ''USB Stack'' specification. If you are using a VINT device, navigate to the product page for the VINT Hub you are using.

[[Image:Javascript_networkserver_webusb_spec.png|center|600px|link=https://cdn.phidgets.com/docs/images/8/80/Javascript_networkserver_webusb_spec.png]]

====Linux Considerations====
Linux restricts access to USB devices to the root user.

To run your C application as a regular user, you'll need to [{{SERVER}}/docs/OS_-_Linux#Setting_udev_Rules set up udev rules] on your system.

=== Library Files ===
If you would like to manually manage the Phidget22 library files, you can download them [https://cdn.phidgets.com/downloads/phidget22/libraries/windows/Phidget22-windevel.zip here].

== Development Environment Configuration ==

=== GCC ===
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
|+ '''Instructions'''
|
The most common tool for C development is GCC, whether used in the command line or through an IDE. GCC is packaged with many other IDEs and packages, so you may already have it installed.

{{hiddenh4|Windows}}
We recommend installing [https://www.cygwin.com/ Cygwin] or [https://sourceforge.net/projects/mingw/ MinGW], ensuring you select all gcc packages when prompted by the installer.

To compile your code, go to the folder where your code is and open the command prompt by typing 'cmd' in the address bar.

The specific command you will use depends on your compiler of choice:
<syntaxhighlight lang=bash>
#Cygwin x86:
gcc example.c -o example -I"/cygdrive/c/Program Files/Phidgets/Phidget22"-L"/cygdrive/c/Program Files/Phidgets/Phidget22/x86" -lphidget22

#Cygwin x64:
gcc example.c -o example -I"/cygdrive/c/Program Files/Phidgets/Phidget22" -L"/cygdrive/c/Program Files/Phidgets/Phidget22" -lphidget22

#MinGW:
gcc example.c -o example -I"C:/Program Files/Phidgets/Phidget22" -L"C:/Program Files/Phidgets/Phidget22/x86" -lphidget22
</syntaxhighlight>

After running the commands above for either Cygwin or MinGW, an executable file called example.exe will be created. Enter the following command to run the program:
<syntaxhighlight lang=bash>
./example.exe
</syntaxhighlight>
{{hiddenh4|MacOS}}
If you don't already have gcc installed, you can get it by installing [https://developer.apple.com/xcode/ Xcode].

To compile the program, enter the following command in the terminal, substituting "example" for the name of your C file:
<syntaxhighlight lang=bash>
gcc example.c -o example -F /Library/Frameworks -framework Phidget22 -I /Library/Frameworks/Phidget22.framework/Headers
</syntaxhighlight>
Finally, run the program by entering the following command in the terminal:
<syntaxhighlight lang=bash>
./example
</syntaxhighlight>
Success! The project is now running with Phidgets.

{{hiddenh4|Linux}}
On Linux, gcc is installed through the package manager:
<syntaxhighlight lang=bash>
apt-get install gcc
</syntaxhighlight>
To compile the program, enter the following command in the terminal, substituting "example" for the name of your C file:
<syntaxhighlight lang=bash>
gcc example.c -o example -lphidget22
</syntaxhighlight>
After compiling, you can run the program by entering the following command in the terminal:
<syntaxhighlight lang=bash>
./example
</syntaxhighlight>
Success! The project is now running with Phidgets.
|-
|}

=== Visual Studio ===
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
|+ '''Instructions'''
| If you want to jump right into a pre-configured project, you can download one on our [https://www.phidgets.com/?view=code_samples&lang=C Code Sample Generator] page. || [[Image:Language_C_VSProject.jpg|center|link=https://cdn.phidgets.com/docs/images/f/f1/Language_C_VSProject.jpg|350px]]
|-
| To configure a new project, follow these steps. ||
|-
| First, create a new Win32 Console Application: || [[Image:Language_C_VS_step1.jpg|center|link=https://cdn.phidgets.com/docs/images/a/a1/Language_C_VS_step1.jpg|350px]]
|-
| If you are using a 64-bit machine, select x64, otherwise, select x86: || [[Image:Language_C_VS_step2.jpg|center|link=https://cdn.phidgets.com/docs/images/6/6b/Language_C_VS_step2.jpg|350px]]
|-
| Next, right click on the source folder and click New Item: || [[Image:Language_C_VS_step3.jpg|center|link=https://cdn.phidgets.com/docs/images/e/e1/Language_C_VS_step3.jpg|350px]]
|-
| Give the source file a name and click Add: || [[Image:Language_C_VS_step4.jpg|center|link=https://cdn.phidgets.com/docs/images/e/e5/Language_C_VS_step4.jpg|350px]]
|-
| Right click your project and access its properties: || [[Image:Language_C_VS_step5.jpg|center|link=https://cdn.phidgets.com/docs/images/1/1e/Language_C_VS_step5.jpg|350px]]
|-
| Go to Configuration Properties -> C/C++ -> General and add this to the additional include directories:
<syntaxhighlight>
C:\Program Files\Phidgets\Phidget22
</syntaxhighlight>
|| [[Image:Language_C_VS_step6.jpg|center|link=https://cdn.phidgets.com/docs/images/d/d3/Language_C_VS_step6.jpg|350px]]
|-
| Go to Configuration Properties -> Linker -> Input and add the appropriate line to additional dependencies:
<syntaxhighlight>
C:\Program Files\Phidgets\Phidget22\phidget22.lib #(for 64-bit systems)
C:\Program Files\Phidgets\Phidget22\x86\phidget22.lib #(for 32-bit systems)
</syntaxhighlight>
|| [[Image:Language_C_VS_step7.jpg|center|link=https://cdn.phidgets.com/docs/images/0/09/Language_C_VS_step7.jpg|350px]]
|-
| Lastly, include the Phidget library at the beginning of your program:
<syntaxhighlight lang=bash>
#include < phidget22.h >
</syntaxhighlight>
||
|-
|}

=== PhidgetSBC Web Interface ===
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
|+'''Instructions'''
|<center>{{#ev:youtube|2hTlVexctqY|rel=0}}</center>
|}

== Example Code ==
Navigate to our [https://www.phidgets.com/?view=code_samples&lang=C Code Sample Generator] to view and download code samples that are tailored to your specific device.

[[Image:Language_c_codesample2.png|center|600px|link=]]

===Phidget Programming Basics===
{{PhidgetProgrammingBasicsLink}}

==API==
[{{SERVER}}/?view=api&lang=C Phidget22 API]

Template:DCMotor ESTOP

2026-05-26T21:45:15Z

Mparadis:

{{#switch: {{{1}}}
| bldc= New BLDC Motor Phidgets include an E-Stop circuit that can be used to trigger a Failsafe state.
| dc = New DC Motor Phidgets include an E-Stop circuit that can be used to trigger a Failsafe state.
| #default = New Phidget motor controllers include an E-Stop circuit that can be used to trigger a Failsafe state.
}}

{| class="wikitable" style="margin:auto;width:75%;text-align:center"
! style="text-align: center;" | E-Stop Input Terminals
! style="text-align: center;" | Result
|-
| Shorted || Normal operation
|-
| Open || Failsafe state activated
|}

The E-Stop input is shorted with a jumper wire by default. If you would like to implement an E-Stop system, we recommend connecting a normally-closed (NC) switch to the E-Stop input.

[[Image:Multi_estop.png|link=|thumb|A 3PST E-stop switch|100px]]
====Multiple Motor Controllers====

If your project uses multiple motor controllers with E-Stops, we recommend wiring them separately because wiring them together can cause ground loops that introduce instability. The best solution is to buy a multi-throw E-Stop switch that provides a separate circuit for each controller.

You can search for on an electronics retailer like Digikey for a DPST-NC switch for two controllers, or 3PST/4PST for three or four.

====Other Considerations====
The E-Stop circuit does not physically interact with the supply voltage or the motor connection. You should not wire your motor, or your supply voltage to this circuit.

File:Multi estop.png

2026-05-26T21:42:37Z

Mparadis:

BLDCMotor API Guide

2026-05-26T19:37:17Z

Mparadis:

{{#seo:|description=Get started with your Brushless DC Motor Phidget}}
[[Category:IntroGuide]]
<div class="nonumtoc">
<div class="toclimit-4">
=Introduction=
[[Image:DCC1120_0.png|thumb|link=https://cdn.phidgets.com/docs/images/3/38/DCC1120_0.png|<center>30V 50A Brushless DC Motor Phidget (DCC1120_0)</center>]]
This guide will provide information about the Brushless DC Motor (BLDC) API to get you up and running with your new BLDC Motor Phidget.

Before starting this guide, visit the Quick Start Guide on your BLDC Motor Phidget's product page for information about wiring and power.

==Guide Compatibility==
<tabber>
Info=
''Select your controller for compatibility information relating to this guide.''
|-|
DCC1120=
[[Image:DCC1120_0.png|link=https://cdn.phidgets.com/docs/images/3/38/DCC1120_0.png|thumb|200px|[{{SERVER}}/?prodid=1334 30V 50A Brushless DC Motor Phidget (DCC1120_0)]]]
The [{{SERVER}}/?prodid=1334 30V 50A Brushless DC Motor Phidget (DCC1120_0)] is fully compatible with this guide.
|-|
DCC1100=
[[Image:DCC1100_0.jpg|link=https://cdn.phidgets.com/docs/images/8/87/DCC1100_0.jpg|thumb|200px|[https://www.phidgets.com/?prodid=1391 Brushless DC Motor Phidget (DCC1100_1)]]]
[https://www.phidgets.com/?prodid=1391 Brushless DC Motor Phidget (DCC1100_1)] considerations:
* Stall Velocity is not covered in this guide. Information on this topic is available in the device API.
|-|
</tabber>

=BLDCMotor API Overview=
==Phidget Control Panel==
After wiring your BLDC Motor Phidget, we recommend opening the [https://www.phidgets.com/docs/Phidget_Control_Panel Phidget Control Panel] on a Windows computer to experiment with key features.

[[Image:DCC1120_0_Panel.png|center|link=]]

When the BLDC Motor Phidget is powered, it will appear up on the Phidget Control Panel device list as shown above. Double-click on the ''BLDC Motor Controller'' entry to view the program.

[[Image:DCC1120_0_BLDC.png|800px|center|link=]]

After opening the program, you will see the screen shown above. The program is split into multiple sections to help you get familiar with your motor controller.
#Phidget Info
#Motor Status
#Controls
#Configuration

In this guide, we will focus on the areas that contain important information about controlling your Brushless DC motor. For information about the Phidget Info section, and the Phidget Control Panel in general, visit our [https://www.phidgets.com/docs/Phidget_Control_Panel Phidget Control Panel] Page.

==Controls==
{{DCBLDCMotor_Controls}}

==Configuration==
This area of the program allows you to try out different configurations with your BLDC Motor Phidget to determine the best fit for your application.

===Drive Mode===
{{DCBLDCMotor_DriveMode|bldc}}

===Rescale Factor===
<center>{{#ev:youtube|SbO3hAuYsAE|rel=0}}</center>

The Rescale Factor allows you to change the units of the following properties:
* [[#Position|Position]]

By default, the units will be in commutations which is dictated by the number of poles/phases your motor and are often non-intuitive. We recommend utilizing the Rescale Factor so your software is easier to understand.

====Example Calculations====
Generally, most users will prefer units of degrees or rotations. To determine an appropriate Rescale Factor, you will need to know the following values:
*Commutations per revolution, equivalent to the number of poles multiplied by the number of phases
*Gearbox ratio (if applicable)

These values will be available from manufacturer data sheets, or directly on the motor.

=====Converting to Degrees=====
Specifications of system:
* Motor gear ratio: 10:1
* Motor poles: 2
* Motor phases: 3

Rescale Factor = 360 / (10<nowiki>*</nowiki>2<nowiki>*</nowiki>3) = '''6.0'''

=====Converting to Rotations=====
Specifications of system:
* Motor gear ratio: 10:1
* Motor poles: 2
* Motor phases: 3

Rescale Factor = 1 / (10<nowiki>*</nowiki>2<nowiki>*</nowiki>3) = '''0.016666667'''

===Braking Enabled===
{{DCBLDCMotor_BrakingEnabled}}

===Surge Current Limit===
{{DCBLDCMotor_SurgeCurrentLimit}}

===Acceleration===
{{DCBLDCMotor_Acceleration}}

===Data Interval===
{{DCBLDCMotor_DataInterval}}

==Motor Status==
This area of the program shows information that has been sent back from the BLDC Motor Phidget.
===Velocity===
{{DCMotor_VelocityStatus}}

===Braking Strength===
{{DCMotor_BrakingStrength}}

===Position===
The most recent Position value reported by the controller. The Position is calculated using Hall Effect sensors mounted inside the motor, therefore, the resolution of the position depends on the motor you are using.

====Other Considerations====
* {{DCMotor_RescaleFactorNote}}
* Consider using an encoder for more accurate position information.

===Active Current Limit===
{{DCMotor_ActiveCurrentLimit}}

===Motor Inductance===
{{DCMotor_MotorInductance}}

==Failsafe==
{{DCMotor_Failsafe}}

===E-Stop===
{{DCMotor_ESTOP|bldc}}

==Errors==
{{DCMotor_Errors|bldc}}

OS - Android

2026-05-25T21:52:16Z

Mparadis: /* Direct USB Connection */

<metadesc>Communicate over USB with sensors, controllers and relays with Phidgets! Program in Android using Android Java.</metadesc>
[[Category:OS]]
{|
|style="vertical-align:middle; width: 60%;"|
==Getting Started with Android==
Welcome to using Phidgets with Android!

If this is your first Phidget, we highly recommend working through the Getting Started guide for your specific Phidget device, which may be found in its [[:Category:UserGuide|user guide]]. If you are ready to go, the first step to creating an Android application with Phidgets is downloading the Phidget libraries on your development machine!
|{{TOC limit|2}}
|}
==Download==
The Phidget libraries for Android development are available here:
*[https://cdn.phidgets.com/downloads/phidget22/libraries/android/phidget22-android.zip Android Java Libraries]

Download and unpack the libraries. You will need to reference these files from your project in order to use Phidgets. This step is covered in detail in the [[Language - Android Java | Android Java page]]. If you need to access older versions of the libraries, [https://www.phidgets.com/downloads/phidget22/libraries/android/ click here].

==Direct USB Connection==
For directly controlling a Phidget with your Android device (i.e. plugging a Phidget directly into your device), you will need to ensure the device is capable of being a USB host. Just having a port that the USB cable can fit into does not necessarily indicate that the port can host a USB device. On the other hand, some phones can use an OTG (on-the-go) cable to allow plugging USB devices into their charging port. Some tablets (like the Samsung Galaxy Tab, for example) have the large 30-pin connectors that can be changed into a USB host using an adapter.

The best way to know before getting your hands on a device is to check its specifications for whether it can serve as a USB host. Alternately, a quick way to figure out if your device can serve as a USB host is to try plugging other devices (such as a mouse, or USB memory stick) into your Android device.

To allow the use of the network and/or USB connections, the following lines must be added to your AndroidManifest.xml file:
<syntaxhighlight>

<uses-permission android:name="android.permission.INTERNET" />


<uses-feature android:name="android.hardware.usb.host" />
</syntaxhighlight>

You'll need to initialize the method that the Android device can use to communicate with the Phidget.

<syntaxhighlight lang="Java">
//Allow direct USB connection of Phidgets
com.phidget22.usb.Manager.Initialize(this);
</syntaxhighlight>

Once the device is closed, to completely clean up after using Phidgets, you must uninitialize the USB connection as follows:

<syntaxhighlight lang="Java">
//Disable USB connection to Phidgets
com.phidget22.usb.Manager.Uninitialize();
</syntaxhighlight>

==Network Server==
In applications where you aren't plugging Phidgets into your Android device directly, you must have a host computer that is running the Phidget Network Server.

[[Image:android-connection.jpg|link=|center]]

*Host computer: the computer that is physically connected to the Phidgets via USB and is running the Phidget Network Server.
*Client computer: a computer running a Phidgets application that accesses Phidgets connected to the host computer. When developing for Android, your Android device acts as the client.

In this case, you will need to install the Phidget libraries on your host computer, and get the Phidget Network Server up and running. Follow the ''Getting Started'' guide, and continue with the ''Network Server'' guide for your operating system. When you are done, come back and finish this guide!
*[[OS - Windows| Windows]]
*[[OS - macOS| macOS]]
*[[OS - Linux| Linux]]
*[[OS - Phidget SBC| Phidget Single Board Computer]]

==Programming Languages==

Now that you have the basics set up, check out the [[Language - Android Java|Android Java]] page for information on how to write code for Phidgets to run on your Android device.

Note that Android Java is NOT the same as mainstream Java. Any Java programs you have will probably need significant modification before they run on Android, including our [[Language - Java|mainstream Java]] Phidget Examples.

==Software License==
By downloading the Android library you agree to adhere to the terms of the [{{SERVER}}/documentation/Licenses/Phidgets_EULA.pdf Phidgets End User License Agreement]. The C API section of Phidget22 is covered by the [https://opensource.org/licenses/BSD-3-Clause The 3-Clause BSD License]. The source code of C API can be found [{{SERVER}}/downloads/phidget22/libraries/linux/libphidget22.tar.gz here].

Language - Java

2026-05-25T21:33:45Z

Mparadis:

{{#seo:|description=Learn how to use Phidget USB devices with Java.}}
[[Category:Language]]

==Get Started==
With the Phidget22 library, it's easy to create Java applications that work with Phidget devices.

==Java Libraries==
During development, we recommend downloading the appropriate installer or package for your [https://www.phidgets.com/docs/Operating_System_Support operating system]. This will place the required Phidget library files in standard locations where Java will look for them. When [[#Deploying Applications|deploying applications]], you can instead include these files manually as part of your application.

====macOS Considerations====
Legacy Phidgets running a HID USB stack require a driver extension (macOS 10.15 and newer) or a kernel extension (macOS 10.14 and earlier). During development, we recommend downloading the appropriate [https://www.phidgets.com/docs/OS_-_macOS#Quick_Downloads package] which will install the extension. When deploying applications, review the README in the [https://cdn.phidgets.com/downloads/phidget22/libraries/macos/Phidget22_macosdevel.zip macOS Development Files] for information about bundling the extension with your application.

=====Determining USB Stack=====
To determine which USB stack your device is running, navigate to the product page and then to the specification tab, and look for the ''USB Stack'' specification. If you are using a VINT device, navigate to the product page for the VINT Hub you are using.

[[Image:Javascript_networkserver_webusb_spec.png|center|600px|link=https://cdn.phidgets.com/docs/images/8/80/Javascript_networkserver_webusb_spec.png]]

====Linux Considerations====
Linux restricts access to USB devices to the root user. To run your Python application as a regular user, you'll need to [{{SERVER}}/docs/OS_-_Linux#Setting_Udev_Rules set up udev rules] on your system.

==Development Environment Configuration==

Before choosing a development environment, make sure you have the [http://www.oracle.com/technetwork/java/index.html Java Development Kit] installed.

===Visual Studio Code===
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
|+ '''Instructions'''
| To start developing with Java in VSCode, open it up and install the '''Extension Pack for Java'''.||[[Image:Language_java_vscode_extension2.png|center|350px|link=https://cdn.phidgets.com/docs/images/b/b4/Language_java_vscode_extension2.png]]
|-
| Next, press '''Ctrl+Shift+P''' to open the command palette, type "java" and select '''Java: Create Java Project'''. || [[Image:Language_java_vscode_createproj.png|center|360px|link=https://cdn.phidgets.com/docs/images/7/78/Language_java_vscode_createproj.png]]
|-
| Select "No Build Tools" and select a directory for the new project. You'll be asked for a project name, and VSCode will create the directory structure. || [[Image:Language_java_vscode_emptyproj.png|center|350px|link=https://cdn.phidgets.com/docs/images/c/c1/Language_java_vscode_emptyproj.png]]
|-
| colspan="2"|You'll need to get a copy of '''phidget22.jar''' to put inside the "lib" folder. [https://www.phidgets.com/downloads/phidget22/libraries/any/Phidget22Java.zip You can download phidget22.jar here].
|-
| colspan="2"| You can now begin writing code in the newly created "App.java" file, or you can download a [[#Example_Code|sample program]] for your device and place it in the "src" folder.
|-
| Compile and run by pressing '''F5''' or by clicking the play button in the top right. || [[Image:Language_java_vscode_run.png|center|350px|link=https://cdn.phidgets.com/docs/images/e/ea/Language_java_vscode_run.png]]
|-
| Once you're ready to compile your project into a .jar executable, click on the '''Java Projects''' section in the explorer. || [[Image:Language_java_vscode_jar.png|center|350px|link=https://cdn.phidgets.com/docs/images/6/65/Language_java_vscode_jar.png]]
|-
| Click on the export icon, and then select your main class and click OK. || [[Image:Language_java_vscode_jar2.png|center|350px|link=https://cdn.phidgets.com/docs/images/7/74/Language_java_vscode_jar2.png]]
|-
| colspan="2"| Now you can run your new .jar file with the following command:
<syntaxhighlight>
java -jar Example.jar
</syntaxhighlight>
|}

===Javac===
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
|+ '''Instructions'''
|The easiest way to allow Java to access the Phidgets Java library is to place a copy of '''phidget22.jar''' in the same folder as your .java program. ||[[Image:Language_java_javac_folder.png|center|350px|link=https://cdn.phidgets.com/docs/images/8/89/Language_java_javac_folder.png]]
|-
|[https://www.phidgets.com/downloads/phidget22/libraries/any/Phidget22Java.zip You can download phidget22.jar here].||
|-
|colspan="2"|To run your program, enter the following command in the command prompt or terminal:
<syntaxhighlight>
javac -classpath .;phidget22.jar example.java
</syntaxhighlight>
Then, enter the following command to run the program:
<syntaxhighlight>
java -classpath .;phidget22.jar example
</syntaxhighlight>
||
|-
| colspan="2"| Once you're ready to compile your project into a .jar executable, create a '''manifest.mf''' file with the following contents:
<syntaxhighlight>
Manifest-Version: 1.0
Main-Class: example
Class-Path: phidget22.jar

</syntaxhighlight>
Make sure there's an empty newline at the bottom of the three lines and a space after each colon.
|-
| colspan="2"| Next, create the .jar file with this command:
<syntaxhighlight>
jar cfm example.jar manifest.mf *.class
</syntaxhighlight>
Once the .jar is created, you can execute it with
<syntaxhighlight>
java -jar example.jar
</syntaxhighlight>

|}

===Netbeans===
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
|+ '''Instructions'''
|The easiest way to allow Java to access the Phidgets Java library is to place a copy of '''phidget22.jar''' in the same folder as your .java program. ||[[Image:Language_java_javac_folder.png|center|350px|link=https://cdn.phidgets.com/docs/images/8/89/Language_java_javac_folder.png]]
|-
|[https://www.phidgets.com/downloads/phidget22/libraries/any/Phidget22Java.zip You can download phidget22.jar here].||
|-
| To start, open NetBeans and create a new project. Select Java Application and follow the steps as directed by Netbeans.|| [[Image:Windows_netbeans1.jpg|center|350px|link=https://cdn.phidgets.com/docs/images/c/c9/Windows_netbeans1.jpg]]
|-
| Next, add a reference to phidget22.jar by right-clicking on the libraries folder. || [[Image:Windows_netbeans2.jpg|center|350px|link=https://cdn.phidgets.com/docs/images/2/2b/Windows_netbeans2.jpg]]
|-
| Navigate to the folder where you downloaded phidget22.jar, and select it. || [[Image:Windows_netbeans3.jpg|center|350px|link=https://cdn.phidgets.com/docs/images/7/76/Windows_netbeans3.jpg]]
|-
| The project now has access to Phidgets. By default, Netbeans should create an executable .jar file in the '''dist''' folder of the project directory when it's built. If it didn't, go to '''Build -> Packaging''' in the project properties and make sure "Build JAR after compiling" is checked.|| [[Image:Windows_netbeans4.png|center|350px|link=https://cdn.phidgets.com/docs/images/7/78/Windows_netbeans4.png]]
|-
| colspan="2"| You can now run the .jar file from the command prompt with:
<syntaxhighlight>
java -jar phidgetTest.jar
</syntaxhighlight>
|}

===Eclipse===
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
|+ '''Instructions'''
| To start, open Eclipse and create a new Java project. Name the project and uncheck the '''create module-info.java file''' box.|| [[Image:java_eclipse_newproj.png|center|350px|link=https://cdn.phidgets.com/docs/images/9/97/Java_eclipse_newproj.png]]
|-
| On the Libraries tab, click Add External JARs and add [https://www.phidgets.com/downloads/phidget22/libraries/any/Phidget22Java.zip phidget22.jar]. to your project as an external jar. Be sure it's being added to the '''Classpath''' and not the module path. || [[Image:java_eclipse_library.png|center|350px|link=https://cdn.phidgets.com/docs/images/1/1b/Java_eclipse_library.png]]
|-
| Create a new Class in your project. || [[Image:java_eclipse_newclass.png|center|350px|link=https://cdn.phidgets.com/docs/images/0/02/Java_eclipse_newclass.png]]
|-
| Name the class, and be sure to check the '''public static void main''' box. Eclipse may require that you add a package name. || [[Image:java_eclipse_newclass2.png|center|350px|link=https://cdn.phidgets.com/docs/images/c/ca/Java_eclipse_newclass2.png]]
|-
| Your project now has access to Phidgets! ||
|-
| Once you're ready to compile your project into a .jar executable, right click on the project in the package explorer and choose '''Export'''. Select '''Runnable JAR file'''. || [[Image:java_eclipse_export.png|center|350px|link=https://cdn.phidgets.com/docs/images/8/8c/Java_eclipse_export.png]]
|-
| Choose the main class and a destination for the .jar file and click finish. || [[Image:java_eclipse_export2.png|center|350px|link=https://cdn.phidgets.com/docs/images/8/8d/Java_eclipse_export2.png]]
|-
| colspan="2"| You can now run the .jar file from the command prompt with:
<syntaxhighlight>
java -jar phidgetTest.jar
</syntaxhighlight>
|}

===Android Studio===
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
|+ '''Instructions'''
| To start, create a new project in Android Studio.|| [[Image:java_as_newproj.png|center|350px|link=]]
|-
| Once you have a new project, be sure to switch the side bar to Project view. || [[Image:java_as_view.png|center|350px|link=]]
|-
| Next, download the [https://cdn.phidgets.com/downloads/phidget22/libraries/android/phidget22-android.zipPhidget22 Android Java libraries], extract the contents, and open the resulting folder. || [[Image:java_as_extract.png|center|350px|link=]]
|-
| Copy the .jar files into the '''app/libs/''' folder of your project. If you are only going to use network Phidgets in your app, then you don't need to copy Phidget22usb.jar into your project.

Right click the jar files you just copied and select '''Add As Library.'''
|[[Image:java_as_jnilibs.png|center|350px|link=]]
|-
|Create a directory called '''jnilibs''' under '''app/src/main''' || [[Image:java_as_jnilibs2.png|center|350px|link=]]
|-
| Copy the remaining folders from the Phidget22 library (containing versions of libphidget22java.so) into the directory you just created. || [[Image:java_as_jnilibs3.png|center|350px|link=]]
|-
| colspan="2"| To allow the use of the network and/or USB connections, the following lines must be added to your AndroidManifest.xml file:
<syntaxhighlight>

<uses-permission android:name="android.permission.INTERNET" />


<uses-feature android:name="android.hardware.usb.host" />
</syntaxhighlight>
Finally, to import the Phidget22 library into your code, add the following line to the rest of your imports:
<syntaxhighlight>
import com.phidget22.*;
</syntaxhighlight>

The project now has access to Phidgets. Next, we'll walk through the steps for writing your own code. ||
|-
| colspan="2"|
By following the instructions for your operating system and compiler above, you now have working examples and a project that is configured. This teaching section will help you understand how the examples were written so you can start writing your own code.

Your main reference for writing Android Java code will be:

* The [https://www.phidgets.com/?view=api Phidget22 API]
* The [https://www.phidgets.com/?view=code_samples&lang=Java Java example code]

'''Step One: Initialize and Open'''

You will need to declare your Phidget object in your code. For example, we can declare a digital input object like this:

<syntaxhighlight lang="java">
DigitalInput device;
</syntaxhighlight>

Next, we need to initialize the method(s) that the Android device can communicate with the Phidget. This is done either by enabling Network Server Discovery, and/or allowing direct USB connections as follows:

<syntaxhighlight lang="java">
//Enable server discovery to list remote Phidgets
this.getSystemService(Context.NSD_SERVICE);
Net.enableServerDiscovery(ServerType.DEVICE_REMOTE);

//Allow direct USB connection of Phidgets
com.phidget22.usb.Manager.Initialize(this);
</syntaxhighlight>

To support remote (network) Phidgets on Android API versions earlier than API version 16, or to connect to Phidget Network Servers with passwords, you will need to add the specific server to your program:

<syntaxhighlight lang="java">
//Add a specific network server to communicate with Phidgets remotely
Net.addServer("ServerName", "192.168.1.105", 5661, "password", 0);
</syntaxhighlight>

After the connection methods are established, the Phidget object needs to be initialized and opened:

<syntaxhighlight lang="java">
device = new DigitalInput();
device.open();
</syntaxhighlight>

Although we are not including it on this page, you should include error handling for all Phidget functions. Here is an example of the previous code with error handling:

<syntaxhighlight lang="java">
try{
device = new DigitalInput();
device.open();
}catch (PhidgetException e) {
e.printStackTrace();
}
</syntaxhighlight>

For more information on error handling with Phidgets, see [[Handling Errors and Logging|this page]].

'''Step Two: Wait for Attachment (plugging in) of the Phidget'''

Simply calling open does not guarantee you can use the Phidget immediately. To use a Phidget, it must be plugged in (attached). We can handle this by using event driven programming and tracking the attach events. Alternatively, we can modify our code so we wait for an attachment:

<syntaxhighlight lang="java">
ch = new DigitalInput();
ch.open(5000); //wait for attach for 5 seconds, if not time out
</syntaxhighlight>

Waiting for attachment will block indefinitely until a connection is made, or until the timeout value is exceeded.

To use events, we have to modify our code:

<syntaxhighlight lang="java">
ch = new DigitalInput();
device.addAttachListener(new AttachListener() {
public void onAttach(final AttachEvent attachEvent) {
AttachEventHandler handler = new AttachEventHandler(device);
synchronized(handler)
{
runOnUiThread(handler);
try {
handler.wait();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
}
});
ch.open();
</syntaxhighlight>

Next, we have to declare the function that will be called when an attach event is fired - in this case the function AttachEventHandler will be called.

<syntaxhighlight lang="java">
class AttachEventHandler implements Runnable {
Phidget device;

public AttachEventHandler(Phidget device) {
this.device = device;
}

public void run() {
TextView attachedTxt = (TextView) findViewById(R.id.attachedTxt);
attachedTxt.setText("Attached");

//notify that we're done
synchronized(this)
{
this.notify();
}
}
}
</syntaxhighlight>

'''Step Three: Do Things with the Phidget'''

We recommend the use of event driven programming when working with Phidgets. In a similar way to handling an attach event as described above, we can also add an event handler for a state change event:

<syntaxhighlight lang="java">
ch = new DigitalInput();
device.addStateChangeListener(new DigitalInputStateChangeListener() {
public void onStateChange(DigitalInputStateChangeEvent stateChangeEvent) {
DigitalInputStateChangeEventHandler handler =
new DigitalInputStateChangeEventHandler(device, stateChangeEvent);
runOnUiThread(handler);
}
});
ch.open();
</syntaxhighlight>

This code will connect a function and an event. In this case, the '''DigitalInputStateChangeEventHandler''' function will be called when there has been a change to the devices input.

Next, we need to create the '''DigitalInputStateChangeEventHandler''' function itself:

<syntaxhighlight lang="java">
class DigitalInputStateChangeEventHandler implements Runnable {
Phidget device;
DigitalInputStateChangeEvent stateChangeEvent;

public DigitalInputStateChangeEventHandler(Phidget device,
DigitalInputStateChangeEvent stateChangeEvent)
{
this.device = device;
this.stateChangeEvent = stateChangeEvent;
}

public void run() {
CheckBox stateBox = (CheckBox) findViewById(R.id.stateBox);
stateBox.setChecked(stateChangeEvent.getState());
}
}
</syntaxhighlight>

If events do not suit your needs, you can also poll the device directly for data using code like this:

<syntaxhighlight lang="java">
boolean state = ch.getState();
</syntaxhighlight>

'''Step Four: Close and Delete'''

At the end of your program, be sure to close your device.

<syntaxhighlight lang="java">
ch.close();
</syntaxhighlight>

Once the device is closed, to completely clean up after using Phidgets, you must uninitialize the USB connection as follows:

<syntaxhighlight lang="java">
//Disable USB connection to Phidgets
com.phidget22.usb.Manager.Uninitialize();
</syntaxhighlight>

Now that you've set up Phidgets in your programming environment, you should read our guide on [[Phidget Programming Basics]] to learn the fundamentals of programming with Phidgets.
|}

=== PhidgetSBC Web Interface ===
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
|+'''Instructions'''
|<center>{{#ev:youtube|gZmWvWXICIA|rel=0}}</center>
'''Note:''' Debian Linux may not have support for the newest JDK by default, so if you're developing your code on another machine, you may have to target an older version of Java in order to run it on the PhidgetSBC.
|}

==Example Code==
Navigate to our [https://www.phidgets.com/?view=code_samples&lang=Java Code Sample Generator] to view and download code samples that are tailored to your specific device.

[[Image:Language_java_codesample.png|center|600px|link=https://cdn.phidgets.com/docs/images/a/af/Language_java_codesample.png]]

===Phidget Programming Basics===
{{PhidgetProgrammingBasicsLink}}

== Deploying Applications ==
The following files are required for your Java application:
* phidget22.jar
* phidget22.dll
* phidget22java.dll

The files can be found in the [https://cdn.phidgets.com/downloads/phidget22/libraries/windows/Phidget22-windevel.zip Development Files]. The .jar file is in lib/java, and the dll files are in lib/c/x64.

Java will look for these files in several locations, including the classpath and the working folder of the project.

==API==
[{{SERVER}}/?view=api&lang=Python Phidget22 API]

File:Java as jnilibs3.png

2026-05-25T21:31:00Z

Mparadis:

File:Java as jnilibs2.png

2026-05-25T21:28:20Z

Mparadis:

File:Java as jnilibs.png

2026-05-25T21:28:04Z

Mparadis:

File:Java as extract.png

2026-05-25T21:27:52Z

Mparadis:

File:Java as view.png

2026-05-25T21:27:24Z

Mparadis:

File:Java as newproj.png

2026-05-25T21:27:06Z

Mparadis:

REL2103 User Guide

2026-05-08T19:15:08Z

Mparadis: /* Part 4: Advanced Topics and Troubleshooting */

__NOINDEX__
__NOTOC__
<metadesc>Use a VINT port with the Solid State Relay Phidget to switch power to a circuit running at up to 30 volts and 10 amps, AC or DC.</metadesc>
[[Category:UserGuide]]
==Part 1: Setup==
{{PT1 Deck Sequence}}

==Part 2: Using Your Phidget==
===About===
The REL2103 is a solid-state relay capable of switching up to 10 amps or controlling power up to 30V. You interact with the REL2103 through the Digital Output Channel Class to turn on or off the power to a circuit.

[[Image:REL2103_About.jpg|link=|center]]

===Explore your Phidget Channels Using the Control Panel===
Double click on the Digital Output channel class under the port your REL2103 is connected to.
[[Image:REL2103_0_Panel_Example.jpg|link=]]

{{UG-Part3}}

==Part 4: Advanced Topics and Troubleshooting==

{{UGC-Start}}
{{UGC-Addressing}}
{{UGC-Entry|Solid State Relays|
|
A solid-state relay is an electrically-controlled switch. For more information about how SSRs work and how to use them, visit the [[Solid State Relay Guide]].}}
{{UGC-Entry|Using the SRC Terminals|
|
The two middle pins on the REL2103, labeled "SRC" give you access to the source of the MOSFETs used to switch your circuit.
If you are switching a DC load, the setup will be advantageous as you can double the maximum current handled by this Phidget (10A to 20A).

[[Image:REL2103-src.jpg|link=|600px]]

The white schematic on the left shows a simplified version of the REL2103's circuitry: An optocoupler that activates two MOSFETs. The black schematic on the right shows how you would hook up a DC circuit to take advantage of the increased maximum current.}}
{{UGC-Entry|Can I use this relay without a VINT Hub?|
|
Unlike most VINT devices that communicate to the VINT Hub by sending packets on the data line, the REL2103 is simply controlled with the port in digital output mode. This means that you can control it with other digital output devices. For example, you can control it with a Phidget 1018 like this:

[[Image:REL2XXX_1018.png|link=|500px]]

Here's a simplified diagram to clarify how the input side of REL2103 works:

[[Image:REL2103_circuit.png|link=|650px]]

The red wire requires 5V to power the opto-isolator diode, and the white wire requires at least 3.3V to switch the MOSFET.
}}
{{UGC-End}}

File:REL2103 circuit.png

2026-05-08T19:14:37Z

Mparadis:

REL2002 User Guide

2026-05-08T15:33:10Z

Mparadis: /* Part 4: Advanced Topics and Troubleshooting */

__NOINDEX__
__NOTOC__
<metadesc>Switch a small digital signal with the Signal Relay Phidget. Switches up to 60W of DC power or 125 VA of AC power.</metadesc>
[[Category:UserGuide]]
==Part 1: Setup==
{{PT1 Deck Sequence}}

== Part 2: Using Your Phidget ==

===About===
[[File:1017_1_Relay_Diagram.jpg|200px|right|link=]]

The REL2002 is a mechanical relay suitable for both AC and DC applications. It is a double-pole double-throw style relay meaning it will switch two circuits at once. You interact with the REL2002 through the Digital Output Channel Class to turn power to your circuit or device on and off .
<div style="clear: both;"></div>
===Explore Your Phidget Channels Using The Control Panel===

Double click on the Digital Output channel class under the port your REL2002 is connected to.

[[Image:REL2002_Panel_Example.jpg|link=|center]]

{{UG-Part3}}

== Part 4: Advanced Topics and Troubleshooting ==
{{UGC-Start}}
{{UGC-Addressing}}
{{UGC-Entry|Mechanical Relays|
|
This relay is an electrically-controlled switch. For more information about how mechanical relays work and how to use them, visit the [[Mechanical Relay Guide]].

}}
{{UGC-Entry|Can I use this relay without a VINT Hub?|
|
Unlike most VINT devices that communicate to the VINT Hub by sending packets on the data line, the REL2002 is simply controlled with the port in digital output mode. This means that you can control it with other digital output devices. For example, you can control it with a Phidget 1018 like this:

[[Image:REL2XXX_1018.png|link=|500px]]

Here's a simplified diagram to clarify how the REL2002 works:

[[Image:REL2002_circuit.png|link=|650px]]

The red wire requires 5V to power the relay coil, and the white wire requires at least 3.3V to switch the MOSFET.
}}

{{UGC-End}}

File:REL2002 circuit.png

2026-05-08T15:32:10Z

Mparadis:

REL2001 User Guide

2026-05-07T22:30:27Z

Mparadis: /* Part 4: Advanced Topics and Troubleshooting */

__NOINDEX__
__NOTOC__
<metadesc>Use a VINT port with the Relay Phidget to switch power to a circuit running at up to 210 watts DC or 1750 volt-amperes AC.</metadesc>
[[Category:UserGuide]]
==Part 1: Setup==
{{PT1 Deck Sequence}}

==Part 2: Using Your Phidget==
===About===
The REL2001 is a mechanical relay suitable for both AC and DC applications. You interact with the REL2001 through the Digital Output Channel Class to turn on and off power to your circuit or device.

[[Image:REL2001_About.jpg|link=|center]]

===Explore your Phidget Channels Using the Control Panel===
Double click on the Digital Output channel class under the port your REL2001 is connected to.

[[Image:REL2001_0_Panel_Example.jpg|link=]]

{{UG-Part3}}

==Part 4: Advanced Topics and Troubleshooting==

{{UGC-Start}}
{{UGC-Addressing}}
{{UGC-Entry|Mechanical Relays|
|
This relay is an electrically-controlled switch. For more information about how mechanical relays work and how to use them, visit the [[Mechanical Relay Guide]].}}
{{UGC-Entry|Can I use this relay without a VINT Hub?|
|
Unlike most VINT devices that communicate to the VINT Hub by sending packets on the data line, the REL2001 is simply controlled with the port in digital output mode. This means that you can control it with other digital output devices. For example, you can control it with a Phidget 1018 like this:

[[Image:REL2XXX_1018.png|link=|500px]]

Here's a simplified diagram to clarify how the REL2001 works:

[[Image:REL2001_circuit.png|link=]]

The red wire requires 5V to power the relay coil, and the white wire requires at least 3.3V to switch the MOSFET.
}}

{{UGC-End}}

File:REL2001 circuit.png

2026-05-07T22:29:30Z

Mparadis:

File:REL2XXX 1018.png

2026-05-07T22:29:18Z

Mparadis:

Language - Swift

2026-04-20T16:09:34Z

Mparadis: /* Swift Libraries */

{{#seo:|description=Learn how to use Phidget USB devices with Swift.}}
[[Category:Language]]

== Get Started ==
With the Phidget22 library, it's easy to create Swift applications that work with Phidget devices.

== Swift Libraries ==
If you've installed the Phidget drivers for [[OS - macOS|macOS]] or [[OS - iOS|iOS]], then you already have the files you need for your project.

====macOS Considerations====
Legacy Phidgets running a HID USB stack require a driver extension (macOS 10.15 and newer) or a kernel extension (macOS 10.14 and earlier). During development, we recommend downloading the appropriate [https://www.phidgets.com/docs/OS_-_macOS#Quick_Downloads package] which will install the extension. When deploying applications, review the README in the [https://cdn.phidgets.com/downloads/phidget22/libraries/macos/Phidget22_macosdevel.zip macOS Development Files] for information about bundling the extension with your application.

=====Determining USB Stack=====
To determine which USB stack your device is running, navigate to the product page and then to the specification tab, and look for the ''USB Stack'' specification. If you are using a VINT device, navigate to the product page for the VINT Hub you are using.

[[Image:Javascript_networkserver_webusb_spec.png|center|600px|link=https://cdn.phidgets.com/docs/images/8/80/Javascript_networkserver_webusb_spec.png]]

== Example Code ==
You can find examples for macOS and iOS on our [https://www.phidgets.com/?view=code_samples&lang=Swift Code Samples] page. Make sure you download one for the correct OS.

[[Image:swift_example2.png|link=|center|750px]]

== XCode Configuration ==
[https://developer.apple.com/xcode/ Xcode] is an IDE provided by Apple that's used to develop code in a wide variety of programming languages, including Swift.

=== macOS ===
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
|+ '''Instructions'''
|colspan="2"|{{hiddenh4|Use Our Examples}}||
|-
|colspan="2"|Start by downloading a [https://www.phidgets.com/?view=code_samples&lang=Swift Swift example] that will work with your Phidget.

Open the folder and run '''Package.swift''' to open it in Xcode.
|-
| Next, simply press run. ||[[Image:Macos_swift_run2.png|link=https://cdn.phidgets.com/docs/images/b/b9/Macos_swift_run2.png|350px]]
|-
| Here's what the VoltageInput example will look like when it's running. Try playing around with the device and experiment with some of its functionality. The next step is configuring a new project and writing your own code. || [[Image:Macos_swift_output.png|link=https://cdn.phidgets.com/docs/images/0/00/Macos_swift_output.png|350px]]
|-
|colspan="2"|{{hiddenh4|Starting a New Project}}
|-
| Create a new XCode project and select a macOS app. || [[Image:Macos_new_proj.png|link=https://cdn.phidgets.com/docs/images/0/04/Macos_new_proj.png|350px]]
|-
| Name the project, select Swift as the language, and continue. || [[Image:Macos_new_nameproject.png|link=https://cdn.phidgets.com/docs/images/f/fb/Macos_new_nameproject.png|350px]]
|-
| Now that your project is created, you need to add the Phidget libraries.

Go to File > '''Add Package Dependencies'''
|[[Image:Macos_swift_addpackage.png|link=https://cdn.phidgets.com/docs/images/1/13/Macos_swift_addpackage.png|350px]]
|-
| This will pop up the Swift package manager. || [[Image:Macos_swift_packageblank.png|link=https://cdn.phidgets.com/docs/images/3/3f/Macos_swift_packageblank.png|350px]]
|-
|Type this URL into the search bar in the top right:
<syntaxhighlight>https://www.phidgets.com/git/phidget22-swift.git</syntaxhighlight>
Then select the phidget22-swift package and click '''Add Package'''.
| [[Image:Macos_swift_packageurl.png|link=https://cdn.phidgets.com/docs/images/f/ff/Macos_swift_packageurl.png|350px]]
|-
|colspan="2"| Now you can access the Phidget libraries by adding the following line to the top of your files:
<syntaxhighlight>import Phidget22Swift</syntaxhighlight>
The project now has access to Phidgets you can begin coding. See [[Phidget Programming Basics]] for guidance on writing your own code.
|}

=== iOS ===
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
|+ '''Instructions'''
|colspan="2"|{{hiddenh4|Use Our Examples}}||
|-
|colspan="2"|Start by downloading a [https://www.phidgets.com/?view=code_samples&lang=Swift Swift example] that will work with your Phidget.

Open the folder and run '''Package.swift''' to open it in Xcode.
|-
| Next, select the type of device you would like the application to run on, and press play. || [[Image:ios_swift_select_target.png|link=https://cdn.phidgets.com/docs/images/9/90/Ios_swift_select_target.png|350px]]
|-
|Here's what the VoltageInput example will look like when it's running. Try playing around with the device and experiment with some of its functionality. The next step is starting a new project and writing your own code.|| [[Image:ios_swift_output.png|link=https://cdn.phidgets.com/docs/images/1/1d/Ios_swift_output.png|200px]]
|-
|colspan="2"|{{hiddenh4|Starting a New Project}}
|-
| Create a new XCode project and select an iOS app. || [[Image:ios_new_proj.png|link=https://cdn.phidgets.com/docs/images/d/d9/Ios_new_proj.png|350px]]
|-
| Name the project, select Swift as the language, and choose which devices will be supported. || [[Image:ios_new_nameproject.png|link=https://cdn.phidgets.com/docs/images/8/86/Ios_new_nameproject.png|350px]]
|-
| Now that your project is created, you need to add the Phidget libraries.
Go to '''File > Add Package Dependencies'''
| |[[Image:Macos_swift_addpackage.png|link=https://cdn.phidgets.com/docs/images/1/13/Macos_swift_addpackage.png|350px]]
|-
| This will pop up the Swift package manager. || [[Image:Macos_swift_packageblank.png|link=https://cdn.phidgets.com/docs/images/3/3f/Macos_swift_packageblank.png|350px]]
|-
|Type this URL into the search bar in the top right:
<syntaxhighlight>https://www.phidgets.com/git/phidget22-swift.git</syntaxhighlight>
Then select the phidget22-swift package and click '''Add Package'''.
| [[Image:Macos_swift_packageurl.png|link=https://cdn.phidgets.com/docs/images/f/ff/Macos_swift_packageurl.png|350px]]
|-
|colspan="2"| Now you can access the Phidget libraries by adding the following line to the top of your files:
<syntaxhighlight>import Phidget22Swift</syntaxhighlight>
The project now has access to Phidgets you can begin coding. See [[Phidget Programming Basics]] for guidance on writing your own code.
|}

==Phidget Programming Basics==
{{PhidgetProgrammingBasicsLink}}

==API==
[{{SERVER}}/?view=api&lang=Swift Phidget22 API]

Language - Objective C

2026-04-20T16:09:04Z

Mparadis: /* Objective C Libraries */

{{#seo:|description=Learn how to use Phidget USB devices with Objective C.}}
[[Category:Language]]

== Get Started ==
With the Phidget22 library, it's easy to create Objective C applications that work with Phidget devices.

== Objective C Libraries ==
If you've installed the Phidget drivers for [[OS - macOS|macOS]] or [[OS - iOS|iOS]], then you already have the files you need for your project.

====macOS Considerations====
Legacy Phidgets running a HID USB stack require a driver extension (macOS 10.15 and newer) or a kernel extension (macOS 10.14 and earlier). During development, we recommend downloading the appropriate [https://www.phidgets.com/docs/OS_-_macOS#Quick_Downloads package] which will install the extension. When deploying applications, review the README in the [https://cdn.phidgets.com/downloads/phidget22/libraries/macos/Phidget22_macosdevel.zip macOS Development Files] for information about bundling the extension with your application.

=====Determining USB Stack=====
To determine which USB stack your device is running, navigate to the product page and then to the specification tab, and look for the ''USB Stack'' specification. If you are using a VINT device, navigate to the product page for the VINT Hub you are using.

[[Image:Javascript_networkserver_webusb_spec.png|center|600px|link=https://cdn.phidgets.com/docs/images/8/80/Javascript_networkserver_webusb_spec.png]]

== Example Code ==
You can find examples for macOS and iOS on our [https://www.phidgets.com/?view=code_samples&lang=Objective-C Code Samples] page.

[[Image:xcode_example2.png|link=https://cdn.phidgets.com/docs/images/3/34/Xcode_example2.png|center|750px]]

== XCode Configuration ==
Xcode is an IDE provided by Apple that can be used to develop code in a wide variety of programming languages, including Objective C.

=== macOS ===
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
|+ '''Instructions'''
|colspan="2"|{{hiddenh4|Use Our Examples}}||
|-
|Start the example by pressing the '''Run''' button:||[[Image:Macos_RunExample.png|link=https://cdn.phidgets.com/docs/images/2/20/Macos_RunExample.png|350px]]
|-
|The application will attach to the Phidget and show you some basic information. Here is an example of a Digital Output channel on a RFID Phidget.||[[Image:Macos_DigitalOutputExample.png|link=https://cdn.phidgets.com/docs/images/9/94/Macos_DigitalOutputExample.png|350px]]
|-
|colspan="2"|You should now have the example up and running for your device. Play around with the device and experiment with some of the functionality. The next step is configuring your project and writing your own code.
|-
|colspan="2"|{{hiddenh4|Starting a New Project}}
|-
|When you are building a project from scratch, or adding Phidgets to an existing project, you'll need to configure your development environment to properly link the Phidget iOS library. To begin, create a new Xcode project and select a macOS Cocoa application.||[[Image:Macos_Cocoa_Application.png|link=https://cdn.phidgets.com/docs/images/d/d2/Macos_Cocoa_Application.png|350px]]
|-
|Navigate to your target's Build Settings and find the '''Framework Search Path''' setting.||[[Image:Macos_frameworksearch2.png|link=https://cdn.phidgets.com/docs/images/9/97/Macos_frameworksearch2.png|350px]]
|-
|Add a reference to '''/Library/Frameworks''' where the Phidget22 framework is installed.||[[Image:Macos_frameworkpath2.png|link=https://cdn.phidgets.com/docs/images/d/d3/Macos_frameworkpath2.png|350px]]
|-
|Next, navigate to the '''Linked Frameworks and Libraries''' setting under '''General''' and add a reference to the Phidget22 framework which is installed to /Library/Frameworks. || [[Image:Macos_linkframework2.png|link=https://cdn.phidgets.com/docs/images/9/9f/Macos_linkframework2.png|350px]]
|-
|colspan="2"|Lastly, navigate to your header file and add a reference to phidget22.h
<syntaxhighlight>#import <Phidget22/phidget22.h></syntaxhighlight>
Your project now has access to Phidgets. See [[Phidget Programming Basics]] for guidance on writing your own code.
|}

=== iOS ===
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
|+ '''Instructions'''
|colspan="2"|{{hiddenh4|Use Our Examples}}||
|-
|colspan="2"|To develop iOS apps in Objective C, we'll be using XCode on a macOS development machine. You'll need both:
* [https://www.phidgets.com/docs/OS_-_macOS Phidget macOS Drivers] installed
* [https://www.phidgets.com/downloads/phidget22/libraries/ios/Phidget22_iOS.zip Phidget iOS Libraries] downloaded
|-
|Unpack the Objective-C example and navigate to Phidget.xcodeproj. Open the file in Xcode.||[[Image:ios_objc_open.png|link=https://cdn.phidgets.com/docs/images/9/9b/Ios_objc_open.png|350px]]
|-
|With '''Phidgets''' as your target, navigate to Build Settings and find the '''Header Search Paths''' setting.||[[Image:ios_objc_header.png|link=https://cdn.phidgets.com/docs/images/c/c8/Ios_objc_header.png|350px]]
|-
| The header file phidget22.h was included in the Phidget iOS libraries download. Add a reference to the folder that contains phidget22.h under the '''Header Search Paths''' setting.||[[Image:ios_objc_header_path.png|link=https://cdn.phidgets.com/docs/images/b/b3/Ios_objc_header_path.png|350px]]
|-
|Next, find the '''Other Linker Flags''' setting.||[[Image:ios_linker.png|link=https://cdn.phidgets.com/docs/images/5/59/Ios_linker.png|350px]]
|-
|Add a reference to the Phidget libraries that were included in the Phidget iOS libraries download.||[[Image:ios_linker_path.png|link=https://cdn.phidgets.com/docs/images/1/17/Ios_linker_path.png|350px]]
|-
|Now that the library files are linked, simply select the type of device you would like the application to run on and press play.||[[Image:ios_simulator.png|link=https://cdn.phidgets.com/docs/images/7/74/Ios_simulator.png|350px]]
|-
|The application will detect any servers that are currently online and have Phidgets connected. Here is an example output.<br/><br/>First, confirm that the Phidgets Example is working. Then, run the example for your specific device by selecting your server and then continue to navigate through the hierarchy until you reach your device. After tapping your device, the example will show automatically. Currently, we have example programs for the following classes:
* DigitalInput
* DigitalOutput
* VoltageInput
* VoltageRatioInput
|[[Image:ios_phidgetapp.png|link=https://cdn.phidgets.com/docs/images/d/d8/Ios_phidgetapp.png|250px]]
|-
|Here is an example of what the VoltageInput example looks like.<br/><br/>You should now have the example up and running for your device. Play around with the device and experiment with some of the functionality. When you are ready, the next step is configuring your project and writing your own code!||[[Image:ios_example_run.png|link=https://cdn.phidgets.com/docs/images/2/25/Ios_example_run.png|250px]]
|-
|colspan="2"|{{hiddenh4|Starting a New Project}}
|-
|Select an iOS application. For this tutorial's purposes, we will use a Single View Application.||[[Image:ios_singleview.png|link=https://cdn.phidgets.com/docs/images/e/e8/Ios_singleview.png|350px]]
|-
|Name the project, select Objective-C as the language, and choose which devices will be supported.||[[Image:ios_nameproject_objc.png|link=https://cdn.phidgets.com/docs/images/1/13/Ios_nameproject_objc.png|350px]]
|-
|colspan="2"|Now that your project is created, you need to add references to the Phidget iOS libraries in the same way you added them to run our example code earlier in this guide.

After you have linked the Phidget iOS libraries, simply add a reference to phidget22.h in your header file:

<syntaxhighlight>#import <Phidget22/phidget22.h></syntaxhighlight>

The project now has access to Phidgets and we are ready to begin coding. See [[Phidget Programming Basics]] for guidance on writing your own code.
|-
|}

==Phidget Programming Basics==
{{PhidgetProgrammingBasicsLink}}

==API==
[{{SERVER}}/?view=api&lang=C Phidget22 API]

Language - C

2026-04-20T16:07:17Z

Mparadis: /* MacOS Considerations */

{{#seo:|description=Learn how to use Phidget USB devices with C and C++.}}
[[Category:Language]]

== Get Started ==
With the Phidget22 library, it's easy to create C or C++ applications that work with Phidget devices.

== C Libraries ==
If you've installed the Phidget drivers for [[OS - Windows|Windows]], [[OS - macOS|MacOS]], or [[OS - Linux|Linux]], then you already have the files you need for your C project.

==== Windows Considerations ====
When adding directories for your project dependencies, add
<syntaxhighlight>
C:/Program Files/Phidgets/Phidget22
</syntaxhighlight>
And for the linker, you can add
<syntaxhighlight>
C:/Program Files/Phidgets/Phidget22/phidget22.lib}} #(for 64-bit systems)
C:/Program Files/Phidgets/Phidget22/x86/phidget22.lib}} #(for 32-bit systems)
</syntaxhighlight>

====macOS Considerations====
Legacy Phidgets running a HID USB stack require a driver extension (macOS 10.15 and newer) or a kernel extension (macOS 10.14 and earlier). During development, we recommend downloading the appropriate [https://www.phidgets.com/docs/OS_-_macOS#Quick_Downloads package] which will install the extension. When deploying applications, review the README in the [https://cdn.phidgets.com/downloads/phidget22/libraries/macos/Phidget22_macosdevel.zip macOS Development Files] for information about bundling the extension with your application.

=====Determining USB Stack=====
To determine which USB stack your device is running, navigate to the product page and then to the specification tab, and look for the ''USB Stack'' specification. If you are using a VINT device, navigate to the product page for the VINT Hub you are using.

[[Image:Javascript_networkserver_webusb_spec.png|center|600px|link=https://cdn.phidgets.com/docs/images/8/80/Javascript_networkserver_webusb_spec.png]]

====Linux Considerations====
Linux restricts access to USB devices to the root user.

To run your C application as a regular user, you'll need to [{{SERVER}}/docs/OS_-_Linux#Setting_udev_Rules set up udev rules] on your system.

=== Library Files ===
If you would like to manually manage the Phidget22 library files, you can download them [https://cdn.phidgets.com/downloads/phidget22/libraries/windows/Phidget22-windevel.zip here].

== Development Environment Configuration ==

=== GCC ===
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
|+ '''Instructions'''
|
The most common tool for C development is GCC, whether used in the command line or through an IDE. GCC is packaged with many other IDEs and packages, so you may already have it installed.

{{hiddenh4|Windows}}
We recommend installing [https://www.cygwin.com/ Cygwin] or [https://sourceforge.net/projects/mingw/ MinGW], ensuring you select all gcc packages when prompted by the installer.

To compile your code, go to the folder where your code is and open the command prompt by typing 'cmd' in the address bar.

The specific command you will use depends on your compiler of choice:
<syntaxhighlight lang=bash>
#Cygwin x86:
gcc example.c -o example -I"/cygdrive/c/Program Files/Phidgets/Phidget22"-L"/cygdrive/c/Program Files/Phidgets/Phidget22/x86" -lphidget22

#Cygwin x64:
gcc example.c -o example -I"/cygdrive/c/Program Files/Phidgets/Phidget22" -L"/cygdrive/c/Program Files/Phidgets/Phidget22" -lphidget22

#MinGW:
gcc example.c -o example -I"C:/Program Files/Phidgets/Phidget22" -L"C:/Program Files/Phidgets/Phidget22/x86" -lphidget22
</syntaxhighlight>

After running the commands above for either Cygwin or MinGW, an executable file called example.exe will be created. Enter the following command to run the program:
<syntaxhighlight lang=bash>
example.exe
</syntaxhighlight>
{{hiddenh4|MacOS}}
If you don't already have gcc installed, you can get it by installing [https://developer.apple.com/xcode/ Xcode].

To compile the program, enter the following command in the terminal, substituting "example" for the name of your C file:
<syntaxhighlight lang=bash>
gcc example.c -o example -F /Library/Frameworks -framework Phidget22 -I /Library/Frameworks/Phidget22.framework/Headers
</syntaxhighlight>
Finally, run the program by entering the following command in the terminal:
<syntaxhighlight lang=bash>
./example
</syntaxhighlight>
Success! The project is now running with Phidgets.

{{hiddenh4|Linux}}
On Linux, gcc is installed through the package manager:
<syntaxhighlight lang=bash>
apt-get install gcc
</syntaxhighlight>
To compile the program, enter the following command in the terminal, substituting "example" for the name of your C file:
<syntaxhighlight lang=bash>
gcc example.c -o example -lphidget22
</syntaxhighlight>
After compiling, you can run the program by entering the following command in the terminal:
<syntaxhighlight lang=bash>
./example
</syntaxhighlight>
Success! The project is now running with Phidgets.
|-
|}

=== Visual Studio ===
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
|+ '''Instructions'''
| If you want to jump right into a pre-configured project, you can download one on our [https://www.phidgets.com/?view=code_samples&lang=C Code Sample Generator] page. || [[Image:Language_C_VSProject.jpg|center|link=https://cdn.phidgets.com/docs/images/f/f1/Language_C_VSProject.jpg|350px]]
|-
| To configure a new project, follow these steps. ||
|-
| First, create a new Win32 Console Application: || [[Image:Language_C_VS_step1.jpg|center|link=https://cdn.phidgets.com/docs/images/a/a1/Language_C_VS_step1.jpg|350px]]
|-
| If you are using a 64-bit machine, select x64, otherwise, select x86: || [[Image:Language_C_VS_step2.jpg|center|link=https://cdn.phidgets.com/docs/images/6/6b/Language_C_VS_step2.jpg|350px]]
|-
| Next, right click on the source folder and click New Item: || [[Image:Language_C_VS_step3.jpg|center|link=https://cdn.phidgets.com/docs/images/e/e1/Language_C_VS_step3.jpg|350px]]
|-
| Give the source file a name and click Add: || [[Image:Language_C_VS_step4.jpg|center|link=https://cdn.phidgets.com/docs/images/e/e5/Language_C_VS_step4.jpg|350px]]
|-
| Right click your project and access its properties: || [[Image:Language_C_VS_step5.jpg|center|link=https://cdn.phidgets.com/docs/images/1/1e/Language_C_VS_step5.jpg|350px]]
|-
| Go to Configuration Properties -> C/C++ -> General and add this to the additional include directories:
<syntaxhighlight>
C:\Program Files\Phidgets\Phidget22
</syntaxhighlight>
|| [[Image:Language_C_VS_step6.jpg|center|link=https://cdn.phidgets.com/docs/images/d/d3/Language_C_VS_step6.jpg|350px]]
|-
| Go to Configuration Properties -> Linker -> Input and add the appropriate line to additional dependencies:
<syntaxhighlight>
C:\Program Files\Phidgets\Phidget22\phidget22.lib #(for 64-bit systems)
C:\Program Files\Phidgets\Phidget22\x86\phidget22.lib #(for 32-bit systems)
</syntaxhighlight>
|| [[Image:Language_C_VS_step7.jpg|center|link=https://cdn.phidgets.com/docs/images/0/09/Language_C_VS_step7.jpg|350px]]
|-
| Lastly, include the Phidget library at the beginning of your program:
<syntaxhighlight lang=bash>
#include < phidget22.h >
</syntaxhighlight>
||
|-
|}

=== PhidgetSBC Web Interface ===
{| style="margin:auto;" class="table-no-border mw-collapsible mw-collapsed"
|+'''Instructions'''
|<center>{{#ev:youtube|2hTlVexctqY|rel=0}}</center>
|}

== Example Code ==
Navigate to our [https://www.phidgets.com/?view=code_samples&lang=C Code Sample Generator] to view and download code samples that are tailored to your specific device.

[[Image:Language_c_codesample2.png|center|600px|link=]]

===Phidget Programming Basics===
{{PhidgetProgrammingBasicsLink}}

==API==
[{{SERVER}}/?view=api&lang=C Phidget22 API]

Reading an I2C Color Sensor

2026-04-13T22:09:26Z

Mparadis: Created page with "<metadesc>A step-by-step example writing code to interface a sensor with the ADP0001.</metadesc> ==Introduction== <center>[https://www.phidgets.com/?prodid=1354 I2C Adapter Phidget (ADP0001_0)] The [https://www.phidgets.com/?prodid=1354 I2C Adapter Phidget] allows you to interface with a wide range of I2C-compatible devices, including sensors, displays, and more...."

<metadesc>A step-by-step example writing code to interface a sensor with the ADP0001.</metadesc>

==Introduction==
[[Image:ADP0001_0_169.jpg|link=https://cdn.phidgets.com/docs/images/f/f5/ADP0001_0_169.jpg|thumb| 450px|<center>[https://www.phidgets.com/?prodid=1354 I2C Adapter Phidget (ADP0001_0)]]]
The [https://www.phidgets.com/?prodid=1354 I2C Adapter Phidget] allows you to interface with a wide range of I2C-compatible devices, including sensors, displays, and more.

In this project, we will use it to read data from an RGB Color Sensor.

===Steps===
To complete this project, we will work through the following steps:
# Determine the device's basic configuration parameters
# Identify the sequence of commands expected by the device
# Connect the device to the I2C Adapter Phidget
# Test the device using the Phidget Control Panel
# Create a custom program.

===Resources===
Information from the following resource will be referenced throughout this project.
* [https://cdn.phidgets.com/docs/images/1/13/TCS34725.pdf TCS34725 RGB Color Sensor IC Datasheet]

==Demonstration==
<center>{{#ev:youtube|dYREkxXgjEA|rel=0}}</center>

==Configuration Parameters==
[[Image:Adp0002_rgb_specs2.png|link=https://cdn.phidgets.com/docs/images/0/05/Adp0002_rgb_specs2.png|thumb|<center>Excerpts from Datasheet</center>]]

During this step, we are looking for the following information:
* Supply Voltage
* Communication Frequency
* Device Address

This information is typically found using the device's product page and/or datasheet. In this case, it was all found on pages 3 to 5 of the datasheet:
* Supply Voltage: 3.3V
* Communication Frequency: 400kHz
* I2C Address: 0x29
<div style="clear:both">

==Command Sequence==
Next, we need to determine the sequence of commands the device is expecting. The TCS34725 datasheet provides a state diagram that we can use to create a list of actions:

[[Image:Adp0002_rgb_states.png|link=https://cdn.phidgets.com/docs/images/0/0e/Adp0002_rgb_states.png|200px|right|thumb|<center>From datasheet (page 7)</center>]]

<br>Based on the state diagram, our list of actions should look like this:

'''Power On Steps''':
# Enable PON (power on) to go from sleep to idle state
# Enable AEN (RGB enabled) to go from idle to RGBC state

After these steps, the device should be able to provide data and respond to commands. We're not using WEN (wait enabled) since we don't need this power-saving feature at this time.

===Writing to TCS34725 Registers===
I2C devices typically expect the following format:

[[Image:Adp0002_an_typicalcomms3.png|link=https://cdn.phidgets.com/docs/images/2/29/Adp0002_an_typicalcomms3.png|600px]]

This protocol diagram from page 12 of the datasheet confirms that the TCS34725 behaves as expected:

[[Image:Adp0002_rgb_protocol.png|link=https://cdn.phidgets.com/docs/images/3/38/Adp0002_rgb_protocol.png|700px]]

The Start (S), Stop (P), Acknowledge (A), and W/R (Write/Read) is all handled internally by the I2C Phidget, so we just need to focus on the command code and data.

==== Command Register ====

The command register lets us tell the sensor which register we want to read or write on our next communication.

[[Image:Adp0002_rgb_cmdreg.png|link=https://cdn.phidgets.com/docs/images/0/0d/Adp0002_rgb_cmdreg.png|750px|center]]

* The first bit is always '1'
* The next two bits control the how the device behaves when requesting multiple bytes
* The last five bits hold the register address (we can ignore the special functions for this project)

Here's an abridged list of registers we'll be using:

[[Image:Adp0002_rgb_registers.png|link=https://cdn.phidgets.com/docs/images/4/48/Adp0002_rgb_registers.png|600px|center]]

===Power On Steps===
====Enable the Sensor====
Enable is managed by register '''0x00''', so our command register will look like this:

[[Image:Adp0002_rgb_cmdenable.png|link=https://cdn.phidgets.com/docs/images/0/03/Adp0002_rgb_cmdenable.png|center|850px]]

So we'll send '''0x80''' to select the enable register.

The enable register is defined in the datasheet as follows:

[[Image:Adp0002_rgb_enablereg.png|link=https://cdn.phidgets.com/docs/images/8/89/Adp0002_rgb_enablereg.png|center|850px]]

* Bits 5, 6, and 7 are '''000''', as they're reserved
* Bit 4 will be '''0''', since we're not using interrupts
* Bit 3 will be '''0''', since we're not using the wait feature
* Bit 2 is '''0''', as it's reserved
* Bit 1 will be '''0''', since we're not enabling RGBC yet
* Bit 0 will be '''1''', to enable power

That gives us '''0x01'''. Together with our command register, our first communication will be '''0x8001'''.
The reason we don't enable RGBC yet is because the device requires a 2.4ms delay between PON and RGBC for reliable startup.

====Enable RGBC====

To enable RGBC we will use the same command we used for power on, but both the AEN bit and the PON bit will be 1. This gives us '''0x8003'''.

=== Reading Data ===

Now that the sensor is initialized, we can start getting data from it. We want to read all eight color registers, so we need to set auto-increment in the command register and point it to the first color register which is at 0x14:

[[Image:Adp0002_rgb_cmdreadauto.png|link=https://cdn.phidgets.com/docs/images/8/87/Adp0002_rgb_cmdreadauto.png|center|850px]]

This means we need to send '''B4'''. After that, we can listen for 8 bytes at a time to get all of our color data.

== Connecting to the ADP0001 ==

The pinout for this sensor is printed on the PCB:

[[Image:I2C_rgb_pinout2.png|link=|130px|left]]

*'''VIN''' - Power
*'''GND''' - Ground
*'''3V3''' - 3.3V Output
*'''SCL''' - Serial Clock
*'''SDA''' - Serial Data
*'''INT''' - Interrupt
*'''LED''' - LED toggle

We don't need the 3.3V output or the interrupt pin for this project. The other pins can be connected to the ADP0001 as follows:

[[Image:I2C_rgb_connection.png|800px|link=https://cdn.phidgets.com/docs/images/d/d9/I2C_rgb_connection.png]]

The LED toggle pin is connected to one of the ADP0001's GPIO pins so we can use it to turn off the LED when not in use.

==Testing in the Phidget Control Panel==
Now that we have the command sequence and our sensor connected, we can use the Phidget Control Panel to confirm our device is working as expected.

===Power On Steps===
We can set the voltage to 3.3V, the frequency to 400kHz, and the address to 0x29.

[[Image:I2C_RGB_ControlPanel.png|link=https://cdn.phidgets.com/docs/images/2/20/I2C_RGB_ControlPanel.png|center]]

Now we can enable the sensor with our command sequence:
* 0x8001 (Power on)
* 0x8003 (RGBC on)
* 0xB4 (auto increment and start from register 0x14)

[[Image:I2C_RGB_ControlPanel2.png|link=https://cdn.phidgets.com/docs/images/4/4f/I2C_RGB_ControlPanel2.png|center]]

===Reading Data===
After sending the command register B4, we can read all color registers by reading 8 bytes at a time.

[[Image:I2C_RGB_ControlPanel3.png|link=https://cdn.phidgets.com/docs/images/0/0a/I2C_RGB_ControlPanel3.png|center]]
[[Image:I2C_RGB_responsegraph.png|link=https://wwwdev.int.phidgets.com/docs/images/9/97/I2C_RGB_responsegraph.png|thumb|<center>Sensor response characteristic (pg.6)<center>]]

This sensor ultimately provides us with four 16-bit values: Clear, Red, Green, and Blue. The clear light value is important for providing brightness calibration. Since the responses of the red, green and blue sensors are normalized to match the response of the clear sensor, we can use it as a baseline to determine color in both bright and dim environments.

In the above image, we get roughly the same value when polling the sensor three times, so the value seems stable. We'll use the bottom row to see if the color makes sense. The data bytes received are sent in register order, so our values are:

* Clear: 0x0FFD
* Red: 0x0A96
* Green: 0x0331
* Blue: 0x0271

Converting to decimal, that's 4093, 2710, 817, 625. We can normalize the last three values using the clear value, and then multiply by 255 and round to get a standard RGB value:

* Red: (2710/4093)*255 = 169
* Green: (817/4093)*255 = 51
* Blue: (625/4093)*255 = 39

This RGB value '''<span style="color:#A93327">(#A93327)</span>''' looks to be correct, as the sensor was pointed at a roll of red electrical tape.

==Writing a Custom Program==
To begin writing a custom program for your Phidget device, navigate to the product page and select the [https://www.phidgets.com/?prodid=1354#Tab_Code_Samples Code Samples tab]. From there, you can customize the code for your own purposes. Here we have modified the Python code sample to match our steps from the Phidget Control Panel.

<syntaxhighlight lang=python>
from Phidget22.Phidget import *
from Phidget22.Devices.DataAdapter import *
import time

def convert_rgbc(data):

c = data[1] << 8 | data[0]

if(c <= 0):
return [0,0,0]

# Combine high and low bytes for each color,
# Then normalize and cap at 255
r = min(255,round((data[3] << 8 | data[2]) / c * 255))
g = min(255,round((data[5] << 8 | data[4]) / c * 255))
b = min(255,round((data[7] << 8 | data[6]) / c * 255))
return [r,g,b]

def main():

adp = DataAdapter()
adp.openWaitForAttachment(5000)

# Set properties
adp.setFrequency(DataAdapterFrequency.FREQUENCY_400kHz)
adp.setDataAdapterVoltage(DataAdapterVoltage.DATAADAPTER_VOLTAGE_3_3V)
addr = 0x29

# Power On
adp.i2cSendReceive(addr, [0x8001], 0)
time.sleep(0.01)

# RGBC On
adp.i2cSendReceive(addr, [0x8003], 0)

# Auto-increment starting with CDATAL
adp.i2cSendReceive(addr, [0xB4], 0)

try:
while True:
rgb = convert_rgbc(adp.i2cSendReceive(addr, [], 8))
print("R: " + str(rgb[0]) + " G: " + str(rgb[1]) + " B: " + str(rgb[2]))
time.sleep(0.5)
pass
except KeyboardInterrupt:
print("Closing...")

adp.close()

main()
</syntaxhighlight>

That’s about it, we went from reading the datasheet to a working script. Not all datasheets are created equal, so if you’re struggling with getting your sensor set up, feel free to ask for help by [https://www.phidgets.com/?view=contact sending us an email].

===Python Graphical Example===
Here is a more in-depth script that displays a graph of the raw values and shows the calculated color after gamma and saturation adjustment.

{{UGC-Start}}
{{UGC-Entry|Full Script (Click to expand)||
<syntaxhighlight lang=python>
import tkinter as tk
import math
from Phidget22.Phidget import *
from Phidget22.Devices.DataAdapter import *
import time

class MultiLineGraph(tk.Canvas):
def __init__(self, parent, lines=4, max_points=100, **kwargs):
super().__init__(parent, bg="black", **kwargs)
self.lines = lines
self.max_points = max_points
self.data = [[] for _ in range(lines)]
self.colors = ["white", "red", "green", "blue"]

def add_points(self, *values):
for i, v in enumerate(values):
self.data[i].append(v)
if len(self.data[i]) > self.max_points:
self.data[i].pop(0)
self.draw()

def draw(self):
self.delete("all")
w = self.winfo_width()
h = self.winfo_height()

if w < 10 or h < 10:
return

# Flatten all visible data
all_values = [v for line in self.data for v in line]

if not all_values:
return

min_val = min(all_values)
max_val = max(all_values)

# Prevent divide-by-zero
if max_val == min_val:
max_val += 1

padding = (max_val - min_val) * 0.1 # 10% padding
min_val -= padding
max_val += padding

for i, line in enumerate(self.data):
if len(line) < 2:
continue

points = []
for j, val in enumerate(line):
x = j / (self.max_points - 1) * w

# Normalize to 0–1
norm = (val - min_val) / (max_val - min_val)

# Flip Y (Tkinter origin is top-left)
y = h - (norm * h)

points.extend([x, y])

self.create_line(points, fill=self.colors[i], width=2)

class App:
def __init__(self, root):
self.root = root
self.root.title("I2C RGB Viewer")
self.adp = DataAdapter()
self.addr = 0x29
self.sat = 1.8
self.gamma = 1.3

# --- Define Gamma Table ---
self.gamma_table = [0] * 256
for i in range(256):
self.gamma_table[i] = int(math.pow(i/255.0,self.gamma)*255)

# --- UI ---
self.graph = MultiLineGraph(root, height=300)
self.graph.pack(fill="both", expand=True)

self.rgb_entry = tk.Entry(root, font=("Consolas", 14))
self.rgb_entry.pack(fill="x")

self.color_panel = tk.Frame(root, height=50, bg="black")
self.color_panel.pack(fill="x")

self.adp.openWaitForAttachment(5000)

# Set properties
self.adp.setFrequency(DataAdapterFrequency.FREQUENCY_400kHz)
self.adp.setDataAdapterVoltage(DataAdapterVoltage.DATAADAPTER_VOLTAGE_3_3V)

# Power On
self.adp.i2cSendReceive(self.addr, [0x8001], 0)
time.sleep(0.01)

# RGBC On
self.adp.i2cSendReceive(self.addr, [0x8003], 0)

# Auto-increment starting with CDATAL
self.adp.i2cSendReceive(self.addr, [0xB4], 0)

# --- Timer ---
self.update_loop()

def read_sensor(self):

data = self.adp.i2cSendReceive(self.addr, [], 8)

# Combine high and low bytes for clear register
raw_c = data[1] << 8 | data[0]

if(raw_c <= 0):
return [0,0,0,0]

# Combine high and low bytes for each colour
raw_r = data[3] << 8 | data[2]
raw_g = data[5] << 8 | data[4]
raw_b = data[7] << 8 | data[6]

return raw_c, raw_r, raw_g, raw_b

def update_loop(self):
raw_c, raw_r, raw_g, raw_b = self.read_sensor()

if raw_c > 0:
# Normalize + gamma
norm_r = self.gamma_table[int(raw_r / raw_c * 255)]
norm_g = self.gamma_table[int(raw_g / raw_c * 255)]
norm_b = self.gamma_table[int(raw_b / raw_c * 255)]

avg = (norm_r + norm_g + norm_b) / 3

# Saturation adjust
norm_r = max(0, min(255, avg + (norm_r - avg) * self.sat))
norm_g = max(0, min(255, avg + (norm_g - avg) * self.sat))
norm_b = max(0, min(255, avg + (norm_b - avg) * self.sat))

hex_color = "#{:02X}{:02X}{:02X}".format(
int(norm_r), int(norm_g), int(norm_b)
)

self.rgb_entry.delete(0, tk.END)
self.rgb_entry.insert(0, hex_color)

self.color_panel.config(bg=hex_color)

# Update graph
self.graph.add_points(raw_c, raw_r, raw_g, raw_b)

# Repeat every 50 ms
self.root.after(50, self.update_loop)

if __name__ == "__main__":
root = tk.Tk()
app = App(root)
root.geometry("600x400")
root.mainloop()
</syntaxhighlight>
}}
{{UGC-End}}

File:TCS34725.pdf

2026-04-13T22:09:02Z

Mparadis:

File:I2C RGB responsegraph.png

2026-04-13T22:03:48Z

Mparadis:

File:I2C RGB ControlPanel3.png

2026-04-13T22:03:36Z

Mparadis:

File:I2C RGB ControlPanel2.png

2026-04-13T22:03:28Z

Mparadis:

File:I2C RGB ControlPanel.png

2026-04-13T22:03:14Z

Mparadis: