hilscher netFIELD Compact X8M, User Manual

Page 1: ...User manual netFIELD Compact X8M Hilscher Gesellschaft f r Systemautomation mbH www hilscher com DOC220302UM01EN Revision 1 English 2022 05 Released Public...

Page 2: ...s 17 3 3 2 Supply voltage 17 3 3 3 RS 232 RS 485 interface 18 3 3 4 USB connectors 20 3 3 5 Console interface 20 3 4 LEDs 21 3 4 1 LEDs of the LAN interface 21 3 4 2 Edge LED 21 4 Commissioning and fi...

Page 3: ...6 1 Device recovery via USB 115 6 2 Useful CLI commands and parameters in Terminal 119 6 2 1 Network Manager 119 6 2 2 Show interface status 119 6 2 3 Activate interface 119 6 2 4 Docker Compose supp...

Page 4: ...er It also provides instructions on how to commission the gateway in the field and how to onboard it in the netFIELD Cloud for remote management optional use case for users subscribers of the netFIELD...

Page 5: ...mportant note you must follow to avoid malfunction Note general note note on further information Instructions 1 Operational step Instruction Instruction 2 Operational step Instruction Instruction Resu...

Page 6: ...loud to edge communication Based on Microsoft Azure IoT Edge Consists of the netFIELD Platform backend and the netFIELD Portal web based user interface frontend The netFIELD Cloud is also referred to...

Page 7: ...etFIELD Compact device to the netFIELD Cloud requires an account subscription for the netFIELD Cloud services https www netfield io Contact your local Hilscher sales representative for information on...

Page 8: ...or manual and local deployment and maintenance of containers Those containers can be pulled from official registries like Docker Hub https hub docker com or any locally hosted Docker registry In case...

Page 9: ...d to survive in harsh environments like unexpected shutdowns with security in mind Easy to port Based on a Yocto project https www yoctoproject org maintained Linux for easy porting to most capable de...

Page 10: ...by using the start stop commands or by enabling the autostart option Also the deletion of containers and images is a part of container management In order to enable the field devices for off and onli...

Page 11: ...k together to realize customer use cases Our powerful message and container oriented architecture provide the highest level of flexibility and reusability when implementing customer solutions with ind...

Page 12: ...te local remote support System and container logging Onboarding in netFIELD Cloud Secure communication to the netFIELD Cloud services Remote device control access via netFIELD Cloud protected by four...

Page 13: ...tructions in this manual before using the product This manual was written for the use of the product by educated personnel When using the product all safety instructions and all valid legal regulation...

Page 14: ...cause an out of memory situation OOM in the Linux kernel leading to temporary delayed application reaction times and limited overall device responsiveness You must therefore consider the memory requir...

Page 15: ...85 interface page 18 5 USB 2 0 type A connector USB connectors page 20 6 USB 2 0 type A connector 7 Console Serial debug console connector UART to USB bridge over Micro USB Console interface page 20 8...

Page 16: ...Hardware description 16 136 3 2 Dimensions Figure 5 Dimensions in millimeters netFIELD Compact X8M User manual DOC220302UM01EN Revision 1 English 2022 05 Released Public Hilscher 2022...

Page 17: ...ondary 100 Mbit s Ethernet port see position 1 The logical name of ETH2 in netFIELD OS is eth1 The factory setting of the IP address of this port is 192 168 253 1 24 3 3 2 Supply voltage The power inp...

Page 18: ...x terminal with the following commands Set remanently to RS 485 sudo sh c echo mode rs485 etc default uart1 systemctl restart uart1 mode Set remanently to RS 232 sudo sh c echo mode rs232 etc default...

Page 19: ...container deployment Note that you must also map the dev ttymxc0 interface into the container The following example shows a docker run command for a Node RED container that would allow the container...

Page 20: ...section Device overview page 15 is linked to an internal UART to USB bridge allowing you to access the netFIELD OS from a terminal program on your engineering PC like e g PuTTY via USB connection Aft...

Page 21: ...ge LED The Edge LED labelled LED see position 8 in section Device overview page 15 is a user programmable yellow green Duo LED It can be controlled via Linux in the directories sys class leds edge_gre...

Page 22: ...y subscribing to the MQTT topic netfield internal netfield app platform connector edge led state Your application s can set the LED state by publishing the following JSON object to this topic schemaVe...

Page 23: ...compatible with your LAN Customize Docker Network Settings Section Docker Network Settings page 81 6 Set local system time Section Set system time page 35 7 Optional Configure netFIELD OS firewall No...

Page 24: ...ce Manager Section Establish LAN connection and login to Local Device Manager page 28 3 If applicable if your LAN uses HTTP HTTPS FTP proxy servers Configure sensorEDGE for using proxy server Section...

Page 25: ...ting Press down the spring loaded lower rail clamps at the back of the mounting bracket Figure 8 Spring loaded rail clamps Hook the upper clamps onto the DIN top hat rail then release the lower clamps...

Page 26: ...clamp screws After having removed the rail clamps hold the rear end of the mounting bracket at the desired position and mark the two places where the threads for the screws are to be cut into the wall...

Page 27: ...bajonet locking mechanism thus attaching the plug securely to the device Device Destruction by Exceeding the Allowed Supply Voltage The supply voltage must not exceed 40 V DC otherwise the device wil...

Page 28: ...e connection warning message when connecting to the device for the first time You can ignore the warning and depending on your browser model select the option to continue to the device s website anywa...

Page 29: ...the DHCP server has assigned to your device you can now access the Local Device Manager directly by entering the assigned IP address into the address bar of your web browser If you do not know the IP...

Page 30: ...he network open your Windows Explorer and select Network You will find the device listed under Other Devices You can recognize it by its model name followed by its host name in brackets Double click t...

Page 31: ...Set IP address on your PC or notebook under Microsoft Windows Open the Windows Control Panel Start menu Windows System Control Panel In the Control panel select Network and Internet then Network and...

Page 32: ...e option to continue to the device s website anyway respectively add an exception rule for this website On the Certificate page of the Local Device Manager you can upload your own trusted certificate...

Page 33: ...log opens Figure 17 Enter new password dialog In the New password field enter a new and safe password then click Sign In button Enter your new password again in the Retype new password field then clic...

Page 34: ...after password change dialog opens Figure 18 Re Authentication dialog Enter your new password once again then click Sign In button The Local Device Manager opens netFIELD Compact X8M User manual DOC22...

Page 35: ...page of the Local Device Manager then click the red date time value next to System Time Figure 19 System time value The Change System Time dialog opens Figure 20 Change System Time dialog Click x butt...

Page 36: ...fic NTP servers Opens further fields for entering the addresses of certain NTP servers that you want to use e g ptbtime1 ptb de You can create a list of several servers the system will use the first s...

Page 37: ...With the Zero Touch method the device registers itself automatically in the portal after it has been put into operation Note that this method is implemented only in certain customer specific Edge Dev...

Page 38: ...arding methods 4 5 2 Onboarding using the Basic method In the navigation panel of the Local Device Manager choose Onboarding The Onboarding page opens Figure 21 Basic onboarding screen in Local Device...

Page 39: ...of the selected upstream protocol Note If necessary you can change the upstream protocol in the netFIELD Portal after onboarding See section Device Navigation Edit device settings Update mask in the o...

Page 40: ...or a second time 4 5 3 Onboarding using the Advanced method Requirements You are logged in to the Local Device Manager You are also logged in to the netFIELD Portal You possess the following rights as...

Page 41: ...device mask in netFIELD Portal Copy the device s hardware ID from your clipboard into the Hardware ID field In the Name field enter a name for your device optional but recommended Keep all other para...

Page 42: ...y created device opens showing the Activation Code that you will have to enter locally on your device Figure 24 Activation Code in portal Copy the Activation Code to your clipboard netFIELD Compact X8...

Page 43: ...URL In the API KEY field enter an API Key that possesses the right to onboard devices See Side note How to copy an API Key for onboarding below Copy the activation code which you have created in step...

Page 44: ...e connects to the portal and is registered there If the process has been successful the following message appears Success Device is now onboarded Side note How to copy an API Key for onboarding For on...

Page 45: ...find out the permissions of an API Key click on the key in the list then open its Permissions tab Figure 26 Example of an API Key permitting to onboard devices To copy the API Key in order to use it i...

Page 46: ...to your clipboard Figure 27 Copy key to clipboard Go to the Onboarding Advanced page in the Local Device Manager of your local device and insert the key into the API KEY field netFIELD Compact X8M Us...

Page 47: ...vigation panel on the left of the screen you can select the available standard management pages 3 Many Hilscher netFIELD application containers like e g netFIELD App Platform Connector or netFIELD App...

Page 48: ...in the netFIELD Portal where you can find the currently available netFIELD documentation including this user manual The icon opens the user menu About Device Manager Shows information about the Local...

Page 49: ...ure etc Model Name Model name of the device Hardware ID Unique identification number of the device To match the required format the ID may be filled up with zeros This ID can also be used in the netFI...

Page 50: ...Equivalent to the transient host name which can be used to connect to the device and which can be changed by DHCP or mDNS at runtime Can contain lower case characters digits dashes and periods with po...

Page 51: ...t belong to the kernel processes Kernel sy Linux kernel processes I O Wait wa Idle while waiting for an I O operation to complete Memory The graph shows the usage of the RAM memory of the netFIELD OS...

Page 52: ...re managed by the netFIELD OS You can also configure your firewall and HTTPS HTTP FTP Proxy server settings here Figure 31 Networking page The Networking page features the following sections Sending R...

Page 53: ...xxxx This is a bridge that was automatically created by the IoT Edge Docker after onboarding the device eth0 This is the ETH 1 LAN interface of the device for the location of the LAN connector on the...

Page 54: ...ce recovery via USB page 115 or you can reactivate the LAN interfaces via the Console interface with a terminal program like e g PuTTY see section Console interface page 20 To query the connectivity s...

Page 55: ...rtual interface virtual Ethernet device of a container in a Docker sit0 Tunneling protocol Simple internet transition for using IPv6 over an existing IPv4 connection Note The IP addresses of the unman...

Page 56: ...default even if you did not configure any Proxy server for your netFIELD OS Do not edit or remove localhost and 127 0 0 1 from the No Proxy list To configure your network Proxy settings click the Edi...

Page 57: ...the Standard Docker or in the IoT Edge Docker may require certain ports on the host system to be open in order to function and communicate properly Therefore make sure that you add these ports to the...

Page 58: ...pen the Firewall configuration page click the FIREWALL link on the Networking page Figure 35 Open Firewall configuration page netFIELD Compact X8M User manual DOC220302UM01EN Revision 1 English 2022 0...

Page 59: ...irewall page Click the button expand in front of a zone s name to show the properties of the zone like Interfaces Sources Allowed Services Forward ports and a brief Description Click the button collap...

Page 60: ...masquerading The source IP address of all outgoing IP packets is replaced by the assigned IP address of the interface Incoming IP packets will be forwarded to the assigned IP address of the interface...

Page 61: ...ere you can define subnets or IP address ranges for which the rules of the zone shall apply Entire subnet of interface Select this option if the rules shall apply to the entire subnet s of the assigne...

Page 62: ...Allowed Services table shows the network services and ports that remain open in a Drop NAT Drop or Block zone Note Secure WWW HTTPS TCP port 443 is by default allowed for all zones and interfaces beca...

Page 63: ...port numbers Figure 38 Add services To find the service port you are looking for you can scroll through the list by using the scroll bar or you can enter the name of the service or the port number int...

Page 64: ...be forwarded to a certain port of another interface e g of an internal interface like a virtual container interface veth whose IP address is not visible to the outside world Port forwarding settings...

Page 65: ...new port forwarding definition is added to the existing zone Control elements in main toolbar 7 The main toolbar on top of the Firewall configuration page features the following control elements Eleme...

Page 66: ...you change the proxy settings locally on your device after onboarding you must synchronize the settings with the netFIELD Portal in order to keep the settings there up to date to synchronize open the...

Page 67: ...rver for your netFIELD OS Do not edit or remove localhost and 127 0 0 1 from the No Proxy list To configure your network proxy settings proceed as follows Note Ask your local network administrator for...

Page 68: ...y server is using If your proxy server requires authentication select the Authentication required option and enter Username and Password of the server In the No Proxy section you can specify destinati...

Page 69: ...separate proxy servers uncheck the Use this proxy server for all protocols option This enables separate configuration fields for the HTTP HTTPS and FTP protocols Figure 44 Separate HTTP HTTPS FTP con...

Page 70: ...Yes to apply the new settings and restart the netFIELD OS Click No to close the dialog without applying the new settings Synchronizing new settings with the cloud If your device was already onboarded...

Page 71: ...now identical with your local settings You can check the new settings in the Device Manager of the netFIELD Portal under Device Manager your device Overview The new settings should be displayed there...

Page 72: ...simply says Wi Fi hardware is not available or disabled 5 4 2 DHCP Server On the DHCP Server tab of the Networking Services page you can configure the DHCP service of netFIELD Edge Devices that are e...

Page 73: ...y the iotedge check tool version 1 2 5 of the IoT Edge runtime which uses the azureiotedge diagnostics container for this Therefore your device must be onboarded in the netFIELD Cloud which enables th...

Page 74: ...in connecting the IoT Edge runtime to the netFIELD Cloud click Check button The result is indicated with a dot OK available Warning Error not available For more information on the checks that are bei...

Page 75: ...nchronize these new settings here with the netFIELD Portal by clicking the Synchronize button The Synchronize button will only be visible if you have actually changed the proxy server settings See als...

Page 76: ...fields enter the credentials of a user of the netFIELD Portal who possesses deleteDevices and offboardedDevices permissions Click Offboard button After successful offboarding the following message app...

Page 77: ...unctions of the devices resource Click Offboard button After successful offboarding the following message appears Success Device is now deleted Note After offboarding all application containers manage...

Page 78: ...HTTPS connection to the netFIELD OS respectively Local Device Manager will be lost You will have to reconnect by specifying the new port number after the IP address in the address bar of your web brow...

Page 79: ...son By default all Hilscher netFIELD Apps use this configuration file Other containers i e non Hilscher application containers that do not require their own customized MQTT client settings can also us...

Page 80: ...successfully only this connection will be used The client will not open multiple connections to multiple servers simultaneously Last Will and Testament Select this option if you want to use the last...

Page 81: ...are not compatible with your company s LAN address configuration i e to avoid an address conflict Note that after changing the address settings of the Standard and or IoT Edge Docker all containers ru...

Page 82: ...bridge as CIDR Suffix or in dotted decimal notation Default CIDR Suffix 24 Default dotted decimal notation 255 255 255 0 Default address pools Here you can define reserve address pools subnets for th...

Page 83: ...ion Default CIDR Suffix 24 Default dotted decimal notation 255 255 255 0 Default address pools Here you can define reserve address pools subnets for the internal IoT Edge Docker bridge networks The de...

Page 84: ...The following picture illustrates the default Docker network configuration Figure 54 Default docker network configuration netFIELD Compact X8M User manual DOC220302UM01EN Revision 1 English 2022 05 Re...

Page 85: ...remote control functions Contact your local Hilscher sales representative for information on the terms and conditions of an account subscription for the netFIELD Cloud services https www netfield io...

Page 86: ...n the Portal for the first time For a detailed description of the remote control functions see section Remote Control in the netFIELD Portal manual DOC190701OIxxEN Figure 55 Remote Access tab In the R...

Page 87: ...ure 56 Login tab In the text field enter the message that shall be displayed then click Save button The message will be displayed in the Sign In dialog of the Local Device Manager Figure 57 Notificati...

Page 88: ...connected to the Internet you can pull here images directly from the Docker Hub by clicking the Get new image link on this page Note The network address settings of the Standard Docker can be managed...

Page 89: ...nd containers blue bar and the amount of mass storage left available Containers The Containers area 3 lists the container instances of the Docker images according to your Filter options settings in th...

Page 90: ...running container Here you can also start stop restart delete or commit the container or change its resource limits Figure 60 Container parameters with terminal window To go back to the Standard Dock...

Page 91: ...search the Docker Hub registry Figure 61 Image Search dialog of Standard Docker In the search field type in a name or search string then press Enter on your keyboard A list featuring the search resul...

Page 92: ...The Run Image dialog opens in which you can configure the container before running it Figure 62 Run Image dialog Note For information about the configuration parameters and environment variables that...

Page 93: ...splay a control button to delete it click on the blue arrow icon on the left of the image in the list Figure 63 Expand image details To manage an image click on it in the list netFIELD Compact X8M Use...

Page 94: ...d Docker overview page click the blue Show all images link in the page header Note The Standard Docker can also be managed by using Docker commands on the embedded Terminal page of the Local Device Ma...

Page 95: ...IoT Edge Docker from the Standard Docker which allows the parameterization of containers before they are started see section Standard Docker page 88 Here you can however change the limits of the reso...

Page 96: ...mages You can choose in the drop down list Images and running containers All downloaded Docker images and currently running containers are displayed default Everything All Docker images and containers...

Page 97: ...the header 1 To expand a box showing concise container details or to display a control button to restart it click on the blue arrow icon on the left Figure 66 Container details expanded To display mor...

Page 98: ...ges area 4 lists the Docker images that were deployed from the netFIELD Portal Note To remove an image and its container from the device you must first delete the container in the Device Manager of th...

Page 99: ...r to display a control button to delete it click on the blue arrow icon on the left Figure 68 IoT image expanded To show more details of an image click on it in the list netFIELD Compact X8M User manu...

Page 100: ...the details page of the container by clicking on it in the list To go back to the IoT Edge Docker overview page click the blue Show all images link in the page header Note The IoT Edge Docker can also...

Page 101: ...d define passwords and access right roles Figure 70 Accounts To create a new user account click on the Create New Account button The Create New Account dialog opens Figure 71 Create new account Fill i...

Page 102: ...and IoT Edge Docker but is otherwise not allowed to make any changes to the netFIELD OS settings The Container Administrator can download container images in the Standard Docker and can also start and...

Page 103: ...n containers in the Local Device Manager Authorized Public SSH Keys This area lists the SSH keys assigned to this account Click on the button to add an SSH key Note With a SSH key pair private and pub...

Page 104: ...n pem format to the netFIELD OS Figure 73 Web Server Certificate page Note The netFIELD OS contains a certificate issued by Hilscher Note that the automatically created certificate is valid for one ye...

Page 105: ...Terminal client program like e g PuTTY via Ethernet and SSH standard port 22 or via serial Console interface UART to USB see section Console interface page 20 Note that file transfer via SCP protocol...

Page 106: ...settings containers user accounts passwords and its cloud registration onboarding will thereby be preserved In a recovery the currently installed OS will be fully replaced by the new recovery image T...

Page 107: ...the process You can restart the containers after having finished the OS Update Figure 75 OS update page Note As an alternative to using the Local Device Manager for your OS update it is also possible...

Page 108: ...y and download the linked recovery swu file 2 Upload the swu file from your local PC to the device On the System Update page simply drag and drop the swu file from your local PC onto the Select or dro...

Page 109: ...rage space on the flash memory To remedy this restart the netFIELD OS then try again The restart will clear remanent data from the flash memory and provide sufficient space for buffering the update fi...

Page 110: ...om left corner of the Local Device Manager screen Note If you have performed a recovery by uploading and installing a recovery image instead of an update all configuration settings have been deleted a...

Page 111: ...op down lists in the header you can filter the messages by time date Severity type and Service i e the service that issued the message Click on a message in the list to display the information in full...

Page 112: ...Figure 80 Services page 1 Click the tabs in the header to select a service type 2 In the filter field you can perform a text search for name and description of a service To remove the filter delete th...

Page 113: ...u to Stop Start or Restart Reload the service The drop down button in the Automatic Startup section allows you to configure the startup behavior of the service like e g masking it in order to prevent...

Page 114: ...eate Timers dialog opens Figure 83 Create timer dialog In the Command field enter the name of the service that shall be triggered by the timer Set all desired parameters then click Save button Note No...

Page 115: ...ttings user accounts and deployed containers of the current netFIELD OS will be deleted This means that you will have to commission and configure your device again after the recovery procedure Note al...

Page 116: ...ection look for the Recovery factory reset via USB memory stick entry and download the linked recovery zip file Unpack the downloaded zip archive on your local PC The unpacked recovery archive contain...

Page 117: ...abel name RECOVERY is mandatory Do not use any other name otherwise the procedure will fail Under Format options check Quick Format option Click Start button Acknowledge the warning message with OK Af...

Page 118: ...f and then on again The device restarts and boots from the connected USB stick It then installs the new netFIELD OS from the USB stick This might take a few minutes Remove the USB stick and start a ne...

Page 119: ...Docker Compose file docker compose file docker compose file yml up d Stop container s via Docker Compose file docker compose file docker compose file yml down 6 2 5 Manage Standard Docker docker docke...

Page 120: ...sable autostart sudo systemctl disable sshd socket Stop SSH Daemon sudo systemctl stop sshd socket 6 2 9 Follow the system log via terminal CLI sudo journalctl f 6 2 10 Configure operating mode of ser...

Page 121: ...onal 120 mA per port Note Maximum load over all three USB ports is 1 A Connector 5 5 x 2 5 mm coaxial input jack with bajonet lock Real time clock Buffering On board battery with 3V and 120mAh SBR1632...

Page 122: ...on 10 90 Storage 5 95 Compliance Electromagnetic compatibility EMC EN 55032 5 EN 61000 6 2 EN 61000 6 3 Safety EN UL IEC 62368 1 Approvals UL In preparation Conformity declarations CE Yes UKCA Yes FCC...

Page 123: ...plant Risk of light burns due to hot device During operation high temperatures can occur on the surface of the device and on the metallic connection sockets If the device was in operation let it cool...

Page 124: ...e at the public collection sites for waste batteries If desired by the customer Hilscher takes back this product including the battery and disposes of it according to the applicable regulations Note t...

Page 125: ...the four fastening screws Figure 89 Open device housing Remove the battery from the device The position of the battery is marked in the photo below Figure 90 Position of battery in device netFIELD Com...

Page 126: ...nd Electronic Equipment WEEE this electronic equipment may not be disposed of as household waste You are legally obliged to dispose of all waste electronic equipment according to national and local re...

Page 127: ...ing materials in the form of a user s manual operator s manual Statement of Work document and all other document types support texts documentation etc are protected by German and international copyrig...

Page 128: ...f said modification Changes shall be taken into account in future manuals and do not represent an obligation of any kind in particular there shall be no right to have delivered documents revised The m...

Page 129: ...listed in the specifications and that there were no defects on the date of acceptance The warranty period shall be 12 months commencing as of the date of acceptance or purchase with express declarati...

Page 130: ...ntial all of the information made available to customer by Hilscher Gesellschaft f r Systemautomation mbH and rights which were disclosed by Hilscher Gesellschaft f r Systemautomation mbH and that wer...

Page 131: ...software must not be exported into such countries for which export is prohibited under US American export control laws and its supplementary provisions You hereby agree to strictly follow the regulati...

Page 132: ...e 19 System time value 35 Figure 20 Change System Time dialog 35 Figure 21 Basic onboarding screen in Local Device Manager 38 Figure 22 Research Hardware ID 40 Figure 23 Add device mask in netFIELD Po...

Page 133: ...Standard Docker 88 Figure 59 Expand concise container details 89 Figure 60 Container parameters with terminal window 90 Figure 61 Image Search dialog of Standard Docker 91 Figure 62 Run Image dialog...

Page 134: ...mat USB STICK dialog window 117 Figure 86 Formatted USB stick 117 Figure 87 Recovery image on USB stick 118 Figure 88 Detach device from mounting bracket 124 Figure 89 Open device housing 125 Figure 9...

Page 135: ...usage 23 Table 10 Tasks for commissioning the netFIELD Compact for Standard Docker usage 24 Table 11 Available Firewall zones 60 Table 12 Elements in Add Zone dialog 61 Table 13 Columns elements in A...

Page 136: ...drone MI Phone 39 02 25007068 E mail info hilscher it Support Phone 39 02 25007068 E mail it support hilscher com Japan Hilscher Japan KK Tokyo 160 0022 Phone 81 0 3 5362 0521 E mail info hilscher jp...