pylon 6 Camera Software Suite for macOS for use with Basler Gigabit Ethernet(GigE) and Basler USB 3.0 (U3V) cameras ================================================================ System Requirements =================== GigE ---- A GigE network adapter that supports jumbo frames is recommended. Concerning performance and reliability we made best experiences with the on-board network adapter. Although the pylon software will work with any GigE network adapter, we recommend to use on-board adapters. USB --- For U3V devices a USB3-capable USB controller is necessary. For best performance and stability we highly recommend to use the on-board USB adapter. Installation ============= The installation of pylon for macOS is described in the INSTALL text document. Camera IP Configuration ======================= The Basler IP Configurator lets you change a camera's IP configuration (e.g., the IP address). As the IP Configurator needs exclusive access to the camera, we recommend to close all other programs (e.g., pylon Viewer) before running the IP Configurator. There are three methods a camera can use for obtaining an IP address: * Static IP: The user can assign a fixed, persistent IP address (Static IP). * DHCP: The camera can retrieve an IP address from a DHCP server. * Auto IP (LLA): The camera can try to automatically negotiate an IP address with the PC to which it is connected (known as Auto-IP, Automatic Private IP Addressing, LLA or Zeroconf). After the IP Configurator has been started, it lists all connected cameras. Select the camera to be configured from the list of detected devices. If the status column indicates that the IP configuration of the camera is not correct, choose the desired method for the IP configuration. When choosing the static IP method, enter a valid IP address and appropriate subnet mask. Usually the "Gateway" edit field can be left empty. Refer to the 'Network Adapter Configuration' section below for more information about assigning IP addresses to the PC's network adapters. Press the "Save" button to write the changes into the camera. After the new settings have been written the camera is reset and the new settings take effect. By choosing the "Assign Temporary IP address" entry from a camera's context menu, a temporary static IP address can be assigned to the camera. The temporary address remains valid until the camera is powered down or until the network plug is removed either from the camera or the PC, but the saved configuration is not changed. This is useful if you want to connect the camera to a different PC or network adapter to modify some settings, but if you want, at the same time, to keep the current one untouched. Network Adapter Configuration ============================= This section describes the correct configuration of the network adapter a camera is connected to. To configure your network adapter, use the tools supplied with your operating system. You can use the pylon IP Configurator to configure the IP settings of the camera (see the 'Camera IP Configuration section' above). IP Address ----------- An easy way to establish a connection to a camera is to assign a fixed IP address to the network adapter the camera is connected to. When using only one camera or when using multiple cameras connected to only one network adapter via a switch, we recommend using Auto-IP (also known as Automatic Private IP Addressing, LLA or Zeroconf). Because Basler GigE cameras support the Auto-IP feature, a Basler GigE camera will be automatically detected when it is connected to a network adapter configured for Auto-IP. When Auto-IP is used, both the camera and the network adapter will automatically choose an unassigned IP address within the 169.254.255.255 subnet. It is important that the network adapter is configured to use Auto-IP. Sometimes, automatic IP addressing is called Local-Link, dynamic address assignment, Zeroconf or LLA. If none of these settings is available, choose DHCP. Most implementations will fall back to Auto-IP if they don't receive a DHCP answer. If for any reason, the network adapter can't be configured to use Auto-IP, assign a fixed, static IP address within the 169.254.255.255 subnet. Make sure the address is not already used. If you don't use a DHCP server for IP address configuration, we recommend to turn off the DHCP option on the camera to shorten the camera's startup time. Attention: When multiple cameras are to be connected to different network adapters either by using multiple network adapters or by using a multi-port network adapter, Auto-IP won't work. The network address for each network adapter must be in a different subnet! Assign a fixed IP address from a different subnet to each adapter a camera is connected to. Example: A computer has two network adapters - eth1 and eth2. One camera is to be connected to each network adapter. Assign the address 192.168.1.1 to eth1 and 192.168.2.1 to eth2, and use the subnet mask 255.255.255.0 for both adapters. Use the IP Configurator (see above) to assign a persistent IP address from the 192.168.1.255 subnet to the camera connected to eth1 and a persistent IP address from the 192.168.2.255 subnet to the camera connected to eth2. An alternative to assigning fixed IP addresses to network adapters and cameras is to run a DHCP server. In this case, DHCP must be activated for the cameras. DHCP can be activated by using the pylon IP Configurator. See the 'Camera IP Configuration' section above for more details about changing a camera's IP configuration. Jumbo Frames ------------- If your network adapter supports jumbo frames, they should be enabled by setting the Maximum Transfer Unit (MTU) size to 8192 or higher. Firewall -------- The firewall must be disabled for network adapters cameras are connected to. Otherwise, device discovery and receiving streaming data may not work. Maximum UDP Socket Buffer Size ============================== The system's maximum UDP receive buffer size should be increased to ensure a stable image acquisition. A maximum size of 2 MB is recommended. This can be achieved by issuing the sudo sysctl -w net.inet.udp.recvspace=2097152 command. To make this setting persistent, you can setup a launch daemon that runs once at system start. sudo -s cat > /Library/LaunchDaemons/maximize.udpbuffer.plist << EOF Label sysctl ProgramArguments /usr/sbin/sysctl -w net.inet.udp.recvspace=2097152 RunAtLoad EOF launchctl load /Library/LaunchDaemons/maximize.udpbuffer.plist exit Optimizing Packet Size ====================== If your network adapter supports jumbo frames, you set the adapter's MTU to 8192 or higher as described in the 'Network Adapter Configuration' section above. In order to take advantage of the adapter's jumbo frame capability, you must also set the packet size used by the camera to 8192. If you are working with the pylon Viewer application, you can set the packet size by first selecting a camera from the tree in the "Device" pane. In the "Features" pane, expand the features group that shows the camera's name, expand the "Transport Layer" parameters group, and set the "Packet Size" parameter to 8192. If you write your own application, use the camera API to set the PacketSize parameter to 8192. Performance Optimization ======================== To increase performance and to minimize CPU load when grabbing images, the following settings should be considered: GigE Devices ------------ * Enable jumbo frames. Many GigE network adapters support so-called jumbo frames, i.e., network packets larger than the usual 1500 bytes. To enable jumbo frames, the maximum transfer unit (MTU) size of the PC's network adapter must be set to a high value. We recommend using a value of 8192 or higher. * Increase the packet size. When jumbo frames are enabled, the camera's packet size must be increased to benefit from the larger packets. The 'Optimizing Packet Size' section above describes how to set the packet size. * Increase the maximum UDP Socket Buffer Size. To ensure a stable image acquisition, increase the system's maximum UDP receive buffer size as described in the 'Maximum UDP Socket Buffer Size' section above. U3V Devices ----------- * Increasing Packet Size. For faster USB transfers you should increase the packet size. You can do this by changing the "Stream Parameters" -> "Maximum Transfer Size" value from inside the pylon Viewer or by setting the corresponding value via the API. Documentation ============= The pylon Camera Software Suite installation installs the pylon Programmer's Guide and API reference and the Basler Product Documentation in the Applications directory. Both can be also accessed directly from pylon Viewer -> ?-menu. Sample Programs =============== The installation disk image contains a set of sample programs. These sample programs are simple command line programs showing the basic pylon use cases. They are located in the "Samples/C++" folder. Each folder contains a top-level Apple Xcode project file that can be used to build the different sample programs. You need to copy the Samples directory to a writable location, e.g., your home directory, before you can use it with Apple Xcode. Camera Emulator =============== In addition to camera transport layers like GigE Vision or USB3 Vision, pylon offers a transport layer that can create simple camera emulation devices. This allows you to develop applications without the need for a physical camera. It is also useful if you want to develop a multi-camera application and don't have enough cameras at hand. Besides emulating image acquisition and standard camera features, camera emulation devices also offer features that a physical camera does not offer: - You can display custom test images, e.g., to optimize your image processing algorithms. - You can generate failed buffers, e.g., to test your exception handling routines. The number of available emulator devices can be controlled by exporting the PYLON_CAMEMU environment variable. For example, export PYLON_CAMEMU=2 will provide two emulator devices. These devices are accessible both by using the pylon C++ API and the pylon Viewer program. When PYLON_CAMEMU is not set, no emulator devices are provided. Note: A maximum of 256 emulator devices are supported. For more information on the camera emulator refer to the Basler Product Documentation, which is included in this package (press F1 in the pylon Viewer). Troubleshooting =============== * Problem: When trying to grab images from multiple cameras, the error message "PrepareGrab (StartStreaming) failed for device" or "Insufficient system resources exist to complete the API" are displayed. Solution: This condition can occur when the number of available open file descriptors is exhausted. Typically, on OSX this is configured to 256 handles per process. Raise this limit using the ulimit command, e.g., ulimit -Sn 4096 This would set the limit for the process to 4096 file handles. To make this setting persistent, you can setup a launch daemon that runs once at system start. sudo -s cat > /Library/LaunchDaemons/limit.maxfiles.plist << EOF Label limit.maxfiles ProgramArguments launchctl limit maxfiles 4096 524288 RunAtLoad ServiceIPC EOF launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist exit * In the event of running into any issues, generate a log file in the following way: - Open the Terminal app (located in /Applications/Utilities). - Run the pylon Viewer by executing the following command line in the Terminal app: /Applications/pylon\ Viewer.app/Contents/Frameworks/pylon.framework/Resources/ Tools/pylon-start-with-logging /Applications/pylon\ Viewer.app Note: If you used a custom path during the pylon installation, "pylon-start-with-logging.sh" and "pylon Viewer.app" may be located in a different directory. - Reproduce the issue, e.g., open a camera in the pylon Viewer, grab an image, close the camera, etc. - Close the pylon Viewer. - A pylonLog.txt document including the logging information will open. - Save the document and send it to Basler Support for further analysis. Version Infos ============= The pylon libraries have been built using the following tools. macOS x86 64bit: These binaries are built with Apple LLVM version 10.0.1 (clang-1001.0.46.4) and Xcode 10.3 (10G8).