MX On Cloud map widgets

Map 위젯은 지리 타일 지도에 엔티티의 실시간 위치를 표시합니다. 차량, 센서, 자산 등 위도와 경도를 보내는 엔티티를 추적할 때 씁니다. 현재 위치, 범위 구역, 지리 경계를 대화형 지도 하나에 모두 보여 줍니다.

Map은 MX On Cloud의 지도 위젯 네 가지 중 하나이며, 위젯마다 쓰임새가 다릅니다:

Map만의 특징:

• 엔티티 속성이나 텔레메트리에서 위도와 경도를 읽어 마커를 실시간으로 놓습니다.
• 여러 지도 공급자와 전환할 수 있는 레이어를 지원합니다: OpenStreet, Google, HERE, Tencent, 사용자 지정.
• 마커, 다각형, 원, Polylines 오버레이를 한 지도에 함께 표시할 수 있습니다.
• 대화형 편집 도구가 있어 위젯에서 바로 마커, 다각형, 원을 놓고, 옮기고, 지울 수 있습니다.

1. 대시보드를 열고 수정 모드로 바꿉니다.
2. 위쪽의 위젯 추가를 클릭하거나, 화면 가운데의 위젯 추가 아이콘을 클릭합니다.
3. Maps 위젯 번들을 엽니다.
4. Map을 선택합니다.
5. 위젯 설정을 마친 다음 추가를 클릭합니다.

지도 배경으로 쓸 타일 레이어를 하나 이상 설정합니다:

• 라벨: 위젯의 레이어 전환기에 표시되는 이름.
• 공급자: OpenStreet, Google, HERE, Tencent, 사용자 지정(타일 서버 URL 입력).
• 레이어: 타일 스타일 — Mapnik, HOT, WorldStreetMap, WorldTopoMap, WorldImagery, Roadmap 등. 쓸 수 있는 옵션은 공급자마다 다릅니다.
• 참조 레이어: 라벨이 붙은 지도 요소(도로, 경계)를 담은 투명 오버레이. 레이어의 톱니바퀴 아이콘 메뉴에서 설정합니다.

전환할 수 있는 레이어를 더 설정하려면 레이어 추가를 클릭합니다. 사용자는 위젯의 레이어 아이콘 버튼으로 레이어를 바꿉니다.

오버레이는 지도에 그려지는 시각 요소입니다. 오버레이 유형마다 자체 데이터 소스에 연결되고 따로 설정합니다.

[[lat1,lng1],[lat2,lng2],...,[latN,lngN]]

[[53.37545,-6.31259],[53.37554,-6.31256],[53.37537,-6.31128],[53.37547,-6.31124]]

{"latitude": value, "longitude": value, "radius": value}

{"latitude": 53.4791, "longitude": -6.5172, "radius": 137.74}

[[lat1,lng1],[lat2,lng2],...,[latN,lngN]]

추가 데이터 소스는 지도에 직접 표시하지 않는 엔티티의 텔레메트리나 속성을 제공합니다. 오버레이 함수의 조건 로직에 씁니다(예: 관련 HMI 장치 데이터에 따라 색이 바뀌는 마커, 정보를 더한 툴팁, 계산한 표시 값).

• 소스: 엔티티 유형 — 기능, 장치, 개체 별명.
• 데이터 키: 엔티티에서 읽을 텔레메트리나 속성 키.

더 설정하려면 데이터 소스 추가를 클릭합니다.

위젯에서 쓸 대화형 컨트롤을 설정합니다.

위치 — 컨트롤 패널의 위치: 왼쪽 위, 오른쪽 위, 왼쪽 아래, 오른쪽 아래.

줌 동작 — 확대/축소 방법을 켭니다:

• 스크롤: 마우스 휠로 확대/축소.
• 더블 클릭: 두 번 클릭하면 확대.
• 컨트롤 버튼: 지도에 + / − 확대/축소 버튼을 표시합니다.

축척 — 거리 축척 막대를 표시합니다: 미터법(km / m) 또는 야드파운드법(mi / ft).

지도 위에 겹쳐 표시할 사용자 지정 버튼을 추가합니다. 버튼마다 클릭하면 미리 정한 동작을 실행합니다.

버튼마다 라벨, 아이콘, 색상, 동작이 있습니다.

쓸 수 있는 동작 유형: 동작 안 함, 새로운 대시보드 상태 탐색, 현재 대시보드 상태 업데이트, 다른 대시보드 탐색, Custom action, Custom action (with HTML template), 모바일 액션, URL 열기, 맵 항목 배치.

맵 항목 배치 동작을 쓰면 사용자가 지도의 한 점을 클릭해 그 위치에 새 엔티티를 만들 수 있습니다. 좌표는 엔티티 속성으로 자동 저장됩니다.

버튼을 더 설정하려면 버튼 추가를 클릭합니다.

동작 설정에 대한 자세한 내용은 위젯 동작을 참고하세요.

• 모든 마커를 포함하도록 지도 경계 맞춤: 불러올 때 보이는 지도 항목이 모두 들어오도록 확대 수준과 위치를 자동으로 맞춥니다. 기본으로 켜져 있습니다.
• 기본 지도 중심 위치: 자동 맞춤을 끄면 쓰는 처음 지도 중심 좌표(위도, 경도).
• 기본 지도 확대 수준: 처음 확대 수준. 값이 클수록 가까이 확대합니다(예: 국가 수준 7, 거리 수준 15).
• 로드할 엔터티 수 제한: 한 번에 불러올 엔티티 최대 수. 데이터가 많을 때 성능 문제를 막습니다(기본값: 16384).

• 제목: 위젯 헤더 라벨. 기본으로 꺼져 있습니다. 패턴 변수로 ${entityName}이나 ${entityLabel}을 쓰거나 고정 문자열을 입력합니다.
• 카드 아이콘: 헤더의 제목 옆에 표시되는 아이콘. 크기(px), 정렬, 색상을 정합니다.

• 배경: 카드 배경색.
• 카드 버튼 표시: 위젯 헤더의 Data export와 전체화면 버튼을 켜고 끕니다.
• 카드 모서리 반경: 모서리 둥글기(px, 기본값: 0px).
• 카드 패딩: 내용과 카드 가장자리 사이의 안쪽 간격(px, 기본값: 8px).

위젯 헤더 버튼 동작을 추가합니다. 위젯 헤더의 아이콘 버튼으로, 클릭하면 설정한 동작을 실행합니다.

쓸 수 있는 동작 유형과 설정은 위젯 동작을 참고하세요.

목표: 온습도 센서 두 개를 지도에 마커로 표시합니다. 마커마다 툴팁에 실시간 텔레메트리를 보여 주고, 센서 상세 상태로 이어지는 링크를 둡니다.

예시 내려받기

이 예시의 완성된 대시보드를 내려받아 내 인스턴스로 가져올 수 있습니다.

사전 준비

1. 기본 대시보드를 내려받아 인스턴스로 가져옵니다. 이 대시보드에는 상태가 두 개 있습니다: Map 위젯을 추가할 메인 상태와, 선택한 센서의 텔레메트리를 표시하도록 이미 설정한 sensor_details 상태.

2. MX On Cloud로 temperature와 humidity 텔레메트리를 보내는 HMI 장치 Sensor A1과 Sensor D1을 만듭니다.

3. HMI 장치마다 다음 서버 속성을 설정합니다:

   Sensor A1:

   • active: true
   • latitude: 53.4711462520356
   • longitude: -6.507791078415879

   Sensor D1:

   • active: true
   • latitude: 53.4836805758458
   • longitude: -6.532912864923978

1단계: 위젯 추가

대시보드를 수정 모드로 열고 Map 위젯을 추가합니다.

2단계: 위젯 설정

지도 유형

지도를 선택하고 레이어 세 개를 설정합니다:

오버레이

오버레이 ⇾ 마커로 가서 마커 추가를 클릭합니다. 데이터 소스와 키를 설정합니다:

• 데이터 소스: 개체 별명 — Sensors라는 새 별칭을 만듭니다
  • 필터 유형: 장치 유형
  • 장치 유형: temperature-sensor
• 위도 키: latitude
• 경도 키: longitude
• 추가 데이터 키: temperature, humidity, active

지도 유형: 레이어 세 개가 있는 지도. 오버레이: 마커, 데이터 소스 엔티티 별칭 Sensors, 위도/경도 키, 추가 데이터 키: temperature, humidity, active. 키: 위도 키, 경도 키, 추가 데이터 키: temperature, humidity, active. 엔티티 별칭 Sensors: 필터 유형 — 장치 유형, 장치 유형 목록 — temperature-sensor.

마커 모양을 설정합니다:

• 마커: 아이콘 — Thermostat, 크기 48
• 색상 함수:

if (data.active !== "true") {
  return 'rgb(255, 0, 0)';
} else {
  return 'rgb(39, 134, 34)';
}

• 라벨 함수:

var color;
if (data.active !== "true") {
  color = 'rgb(255, 0, 0)';
} else {
  color = 'rgb(39, 134, 34)';
}
return '<span style="border: solid ' + color + '; border-radius: 10px; color: ' + color + '; background-color: #fff; padding: 3px 5px; font-size: 14px; position: relative; bottom: 6px;">' +
  '${entityLabel}' +
'</span>';

• 툴팁 함수:

const unit = { from: '°C', METRIC: '°C', IMPERIAL: '°F', HYBRID: '°C' };
var usrUnit = ctx.unitService.getTargetUnitSymbol(unit);
var unitValue = ctx.unitService.convertUnitValue(data.temperature, unit).toFixed(1);
return `<b>${data.entityName}</b><br/><br/><b>Temperature:</b> ${unitValue} ${usrUnit}<br/><b>Humidity:</b> ${data.humidity} %<br/><br/><link-act name="navigate_to_details">Sensor details</link-act><br/>`;

• 태그 동작:
  • 이름: navigate_to_details
  • 동작: 새로운 대시보드 상태 탐색
  • 대상 대시보드 상태: sensor_details

모양

제목 표시를 끕니다.

카드 모양

카드의 전체화면 버튼을 끕니다.

추가를 클릭해 위젯을 대시보드에 넣습니다. 필요하면 크기와 위치를 조정한 다음 대시보드를 저장합니다.

3단계: 마커 다루기

마커를 클릭하면 툴팁에서 센서의 온도와 습도를 볼 수 있습니다. Sensor details를 클릭하면 상세 상태로 이동해 지난 1시간의 현재 측정값과 과거 측정값을 볼 수 있습니다.

마커를 클릭하면 추가 정보를 볼 수 있습니다. 툴팁에 온도와 습도 값이 표시됩니다. Sensor details를 클릭하면 센서 상세 상태로 이동합니다. 센서 상세 상태는 지난 1시간의 현재·과거 온습도 데이터를 보여 줍니다.

결과

Map 위젯이 두 센서를 지도에 온도 조절기 아이콘으로 보여 줍니다. 활성이면 초록, 비활성이면 빨강입니다. 마커를 클릭하면 실시간 텔레메트리와 센서의 과거 데이터 화면 링크가 나타납니다.

마커가 보이지 않음:

• 엔티티에 latitude와 longitude 속성이나 텔레메트리 값이 있는지 확인합니다.
• 위젯 구성의 좌표 키 이름이 엔티티의 실제 키 이름과 정확히 같은지 확인합니다.
• 값이 문자열이나 null이 아닌 올바른 소수 좌표인지 확인합니다.

다각형이나 원이 표시되지 않음:

• 엔티티에 속성 키가 있고 값 형식이 올바른지 확인합니다.
• 다각형: [[lat1,lng1],[lat2,lng2],...].
• 원: {"latitude":value,"longitude":value,"radius":value}.

폴리라인이 표시되지 않음:

• 엔티티에 올바른 키 이름의 폴리라인 속성이 있는지 확인합니다.
• 속성 값이 기대하는 형식을 따르는지 확인합니다: [[lat1,lng1],[lat2,lng2],...].

지도가 빈 화면으로 열림:

• Google Maps, HERE, Tencent는 MX On Cloud 시스템 설정에 API 자격 증명이 설정되어 있는지 확인합니다.
• OpenStreetMap은 자격 증명이 필요 없습니다.

높은 확대 수준에서도 마커가 묶임:

• 마커 오버레이에서 지도 마커 클러스터링 사용이 켜져 있는지 확인합니다. 모든 확대 수준에서 개별 마커가 필요하면 끕니다.